FastOG
주제

React 앱용 OG 이미지 생성

FastOG API를 사용하여 React로 og:image를 생성합니다. Dynamic API 구독(대시보드에서 API 키 생성)을 기반으로 하며, 구독제 방식이고 HMAC으로 보안이 강화됩니다. 이 가이드에서는 HMAC 서명된 OG 이미지 URL을 생성하는 서명 유틸리티(signer utility)를 만들고, 동적 Open Graph 이미지를 즉시 렌더링하는 방법을 설명합니다. 배포 전에 무료 OG 이미지 테스터(Free OG Image Tester)를 사용하여 디자인을 미리 확인하세요.

빠른 시작

1. 서명 유틸리티 생성

javascript
// src/utils/og-image-signer.js
export async function generateSignedOgUrl(params, options = {}) {
    const {
        baseUrl = "https://fastog.com/api/v1/og",
        apiKey = import.meta.env.VITE_FASTOG_API_KEY ||
            process.env.REACT_APP_FASTOG_API_KEY,
        hmacSecret = import.meta.env.VITE_FASTOG_HMAC_SECRET ||
            process.env.REACT_APP_FASTOG_HMAC_SECRET,
    } = options;

    if (!apiKey || !hmacSecret) {
        throw new Error("Missing FASTOG_API_KEY or FASTOG_HMAC_SECRET");
    }

    // RFC-3986 percent-encoding: keep A-Za-z0-9-._~
    const enc = (s) =>
        encodeURIComponent(s).replace(
            /[!'()*]/g,
            (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
        );

    // Every query param except the signature, INCLUDING key
    const all = { ...params, key: apiKey };

    // Canonical query: sorted enc(key)=enc(value) pairs joined with &
    const pairs = [];
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? v : [v]) {
            pairs.push(`${enc(k)}=${enc(vv)}`);
        }
    }
    pairs.sort();
    const canonical = pairs.join("&");

    // Sign the exact bytes the server will verify (Web Crypto HMAC-SHA256)
    const signingKey = await crypto.subtle.importKey(
        "raw",
        new TextEncoder().encode(hmacSecret),
        { name: "HMAC", hash: "SHA-256" },
        false,
        ["sign"],
    );
    const signature = Array.from(
        new Uint8Array(
            await crypto.subtle.sign(
                "HMAC",
                signingKey,
                new TextEncoder().encode(`GET/api/v1/og\n${canonical}`),
            ),
        ),
    )
        .map((b) => b.toString(16).padStart(2, "0"))
        .join("");

    // Build the URL from the same pairs so bytes match the canonical form
    const url = new URL(baseUrl);
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? v : [v]) {
            url.searchParams.append(Array.isArray(v) ? `${k}[]` : k, vv);
        }
    }
    url.searchParams.set("s", signature);

    return url.toString();
}

⚠️ 중요: React SPA에서는 서명이 클라이언트 측에서 수행됩니다. 프로덕션 환경에서는 HMAC 비밀 키를 안전하게 유지하기 위해 서명을 백엔드 API 라우트로 이동하세요.

Express 백엔드

javascript
// server/routes/og.js
import express from "express";
import crypto from "crypto";

const router = express.Router();

router.get("/api/og", (req, res) => {
    const { title, template = "default", ...params } = req.query;

    if (!title) {
        return res.status(400).json({ error: "Missing title" });
    }

    const apiKey = process.env.FASTOG_API_KEY;
    const hmacSecret = process.env.FASTOG_HMAC_SECRET;

    const enc = (s) =>
        encodeURIComponent(s).replace(
            /[!'()*]/g,
            (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
        );

    const all = { template, title, ...params, key: apiKey };

    const pairs = [];
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? v : [v]) {
            pairs.push(`${enc(k)}=${enc(vv)}`);
        }
    }
    pairs.sort();
    const canonical = pairs.join("&");

    const signature = crypto
        .createHmac("sha256", hmacSecret)
        .update(`GET/api/v1/og\n${canonical}`)
        .digest("hex");

    const url = new URL("https://fastog.com/api/v1/og");
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? v : [v]) {
            url.searchParams.append(Array.isArray(v) ? `${k}[]` : k, vv);
        }
    }
    url.searchParams.set("s", signature);

    res.json({ ogImageUrl: url.toString() });
});

export default router;

React 컴포넌트

jsx
// src/components/OgImage.jsx
import { useState, useEffect } from "react";

export function useOgImage(params) {
    const [ogImageUrl, setOgImageUrl] = useState(null);

    useEffect(() => {
        const searchParams = new URLSearchParams(params);
        fetch(`/api/og?${searchParams}`)
            .then((res) => res.json())
            .then((data) => setOgImageUrl(data.ogImageUrl))
            .catch((err) => console.error("Failed to generate OG image:", err));
    }, [JSON.stringify(params)]);

    return ogImageUrl;
}

블로그 포스트 예시

jsx
// src/pages/BlogPost.jsx
import { useEffect, useState } from "react";
import { useOgImage } from "../components/OgImage";

export default function BlogPost({ post }) {
    const ogImageUrl = useOgImage({
        title: post.title,
        template: "blog",
        subtitle: post.excerpt,
    });

    useEffect(() => {
        const ogImage = document.querySelector('meta[property="og:image"]');
        if (ogImage && ogImageUrl) {
            ogImage.setAttribute("content", ogImageUrl);
        }
    }, [ogImageUrl]);

    return (
        <article>
            <h1>{post.title}</h1>
            <p>{post.excerpt}</p>
        </article>
    );
}

React Helmet (SSR)

jsx
// src/pages/BlogPost.jsx
import { Helmet } from "react-helmet-async";
import { useOgImage } from "../components/OgImage";

export default function BlogPost({ post }) {
    const ogImageUrl = useOgImage({
        title: post.title,
        template: "blog",
        subtitle: post.excerpt,
    });

    return (
        <>
            <Helmet>
                <meta
                    property="og:image"
                    content={ogImageUrl || "/fallback-og.png"}
                />
                <meta property="og:title" content={post.title} />
                <meta property="og:description" content={post.excerpt} />
            </Helmet>
            <article>
                <h1>{post.title}</h1>
            </article>
        </>
    );
}

Next.js (React 프레임워크)

Next.js에 대해서는 전용 Next.js App Router 및 Next.js Pages Router 튜토리얼을 참조하십시오.

Remix

jsx
// app/routes/blog.$slug.jsx
import { json } from "@remix-run/node";
import { useLoaderData } from "@remix-run/react";
import { generateSignedOgUrl } from "~/lib/og-image-signer.server";

export async function loader({ params }) {
    const post = await getPost(params.slug);

    const ogImageUrl = generateSignedOgUrl({
        template: "blog",
        title: post.title,
        subtitle: post.excerpt,
    });

    return json({ post, ogImageUrl });
}

export function meta({ data }) {
    return [
        { title: data.post.title },
        { property: "og:image", content: data.ogImageUrl },
        { property: "og:title", content: data.post.title },
    ];
}

export default function BlogPost() {
    const { post } = useLoaderData();

    return (
        <article>
            <h1>{post.title}</h1>
        </article>
    );
}

서버 사이드 서명자 (Node.js)

javascript
// lib/og-image-signer.server.js
import crypto from "crypto";

export function generateSignedOgUrl(params, options = {}) {
    const {
        baseUrl = "https://fastog.com/api/v1/og",
        apiKey = process.env.FASTOG_API_KEY,
        hmacSecret = process.env.FASTOG_HMAC_SECRET,
    } = options;

    // RFC-3986 percent-encoding: keep A-Za-z0-9-._~
    const enc = (s) =>
        encodeURIComponent(s).replace(
            /[!'()*]/g,
            (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
        );

    // Every query param except the signature, INCLUDING key
    const all = { ...params, key: apiKey };

    // Canonical query: sorted enc(key)=enc(value) pairs joined with &
    const pairs = [];
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? v : [v]) {
            pairs.push(`${enc(k)}=${enc(vv)}`);
        }
    }
    pairs.sort();
    const canonical = pairs.join("&");

    // Sign the exact bytes the server will verify
    const signature = crypto
        .createHmac("sha256", hmacSecret)
        .update(`GET/api/v1/og\n${canonical}`)
        .digest("hex");

    // Build the URL from the same pairs so bytes match the canonical form
    const url = new URL(baseUrl);
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? v : [v]) {
            url.searchParams.append(Array.isArray(v) ? `${k}[]` : k, vv);
        }
    }
    url.searchParams.set("s", signature);

    return url.toString();
}

환경 변수

bash
# .env (Vite)
VITE_FASTOG_API_KEY=sk_your_full_api_key_here
VITE_FASTOG_HMAC_SECRET=your_64_char_hex_secret_here

# .env (Create React App)
REACT_APP_FASTOG_API_KEY=sk_your_full_api_key_here
REACT_APP_FASTOG_HMAC_SECRET=your_64_char_hex_secret_here

# Server .env
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here

흔한 실수

클라이언트 코드에 HMAC 시크릿 노출

❌ 잘못된 예:

javascript
// In browser code
const ogUrl = generateSignedOgUrl(params, {
    hmacSecret: import.meta.env.VITE_FASTOG_HMAC_SECRET,
});

✅ 올바른 예:

javascript
// Call your backend API
const res = await fetch(`/api/og?title=${post.title}`);
const { ogImageUrl } = await res.json();

메타 태그를 업데이트하지 않는 경우

소셜 크롤러는 초기 HTML에 메타 태그가 필요합니다. 올바른 OG 이미지 지원을 위해 SSR(Next.js, Remix) 또는 백엔드 프록시를 사용하세요.

전체 API 참조

무료로 체험해 보세요 — 가입 불필요

몇 초 만에 동적 OG 이미지를 미리 보고 테스트하세요.

무료 OG 이미지 테스터 열기
LocaFile AI AI localization for games, apps, subtitles & sites SubtoVTT Convert & clean subtitle files BeCaSimulations Indie game studio

A BeCaSimulations site