FastOG
Konu

React Uygulamaları için OG Görseli Oluşturma

FastOG API'sini kullanarak React ile og:image oluşturun — Dynamic API aboneliğiyle (API anahtarınızı panelde oluşturun), abonelik tabanlı, HMAC ile güvence altına alınmıştır. Bu kılavuz, HMAC imzalı OG görseli URL'leri için bir imzalayıcı yardımcı programı (signer utility) oluşturmayı ve dinamik Open Graph görsellerini anında nasıl işleyeceğinizi gösterir. Yayınlamadan önce tasarımınızı önizlemek için Ücretsiz OG Görseli Test Aracı'nı deneyin.

Hızlı Başlangıç

1. İmzalayıcı yardımcı programını oluşturun

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();
}

⚠️ Önemli: React SPA'larında imzalama işlemi istemci tarafında gerçekleşir. Üretim ortamı için, HMAC sırrını güvende tutmak adına imzalamayı bir arka uç API rotasına taşıyın.

Express Backend

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 Bileşeni

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;
}

Blog Yazısı Örneği

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 Framework)

Next.js için özel Next.js App Router ve Next.js Pages Router eğitimlerine bakın.

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>
    );
}

Sunucu tarafı imzalayıcı (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();
}

Ortam Değişkenleri

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

Yaygın Hatalar

HMAC Gizli Anahtarını İstemci Kodunda Açığa Çıkarmak

❌ Yanlış:

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

✅ Doğru:

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

Meta Etiketlerini Güncellememek

Sosyal tarayıcılar, meta etiketlerine başlangıçtaki HTML içinde ihtiyaç duyar. Doğru OG görseli desteği için SSR (Next.js, Remix) veya bir arka uç proxy kullanın.

Tam API Referansı

Ücretsiz deneyin — kayıt gerekmez

Dinamik OG görsellerini saniyeler içinde önizleyin ve test edin.

Ücretsiz OG Görsel Test Aracını Aç
LocaFile AI AI localization for games, apps, subtitles & sites SubtoVTT Convert & clean subtitle files BeCaSimulations Indie game studio

A BeCaSimulations site