FastOG
Topik

Membuat Gambar OG di Next.js — API og:image Dinamis

Buat gambar OG di Next.js dengan API Dinamis berbasis langganan dari FastOG — dengan langganan API Dinamis (buat kunci API Anda di dasbor), dan Penguji Gambar OG Gratis menampilkan pratinjau gambar Anda sebelum Anda menulis satu baris kode pun. Panduan ini menunjukkan cara membuat gambar Open Graph dinamis dengan URL yang ditandatangani HMAC, langsung dari Next.js App Router.

Memulai dengan Cepat

1. Buat utilitas penanda tangan

javascript
// lib/og-image-signer.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;

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

2. Atur variabel lingkungan

bash
# .env.local
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here
typescript
// app/blog/[slug]/page.tsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";
import { getPost } from "@/lib/posts";

interface PageProps {
    params: Promise<{ slug: string }>;
}

export async function generateMetadata({ params }: PageProps) {
    const { slug } = await params;
    const post = await getPost(slug);

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

    return {
        title: post.title,
        description: post.excerpt,
        openGraph: {
            title: post.title,
            description: post.excerpt,
            images: [
                {
                    url: ogImageUrl,
                    width: 1200,
                    height: 630,
                    alt: post.title,
                },
            ],
            type: "article",
        },
        twitter: {
            card: "summary_large_image",
            images: [ogImageUrl],
        },
    };
}

export default async function BlogPost({ params }: PageProps) {
    const { slug } = await params;
    const post = await getPost(slug);

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

Pola 2: Proksi Rute API

Gunakan pola ini jika Anda ingin menyimpan cache gambar OG atau menambahkan logika khusus.

typescript
// app/api/og/route.ts
import { NextRequest, NextResponse } from "next/server";
import { generateSignedOgUrl } from "@/lib/og-image-signer";

export async function GET(request: NextRequest) {
    try {
        const { searchParams } = new URL(request.url);
        const title = searchParams.get("title");
        const template = searchParams.get("template") || "default";

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

        const ogImageUrl = generateSignedOgUrl({
            template,
            title,
        });

        // Option 1: Redirect to FastOG
        return NextResponse.redirect(ogImageUrl);

        // Option 2: Fetch and return image (for caching)
        // const response = await fetch(ogImageUrl);
        // const imageBuffer = await response.arrayBuffer();
        // return new NextResponse(imageBuffer, {
        //     headers: {
        //         'Content-Type': 'image/png',
        //         'Cache-Control': 'public, max-age=31536000, immutable',
        //     },
        // });
    } catch (error) {
        console.error("OG image generation failed:", error);
        return NextResponse.json(
            { error: "Failed to generate OG image" },
            { status: 500 },
        );
    }
}

Penggunaan dalam templat:

typescript
<meta property="og:image" content={`/api/og?title=${encodeURIComponent(post.title)}`} />

Pola 3: Komponen Server Secara Langsung

typescript
// app/blog/[slug]/page.tsx
import { generateSignedOgUrl } from '@/lib/og-image-signer';

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

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

    return (
        <article>
            <head>
                <meta property="og:image" content={ogImageUrl} />
                <meta property="og:title" content={post.title} />
            </head>
            {/* ... post content ... */}
        </article>
    );
}

Contoh E-commerce

typescript
// app/products/[id]/page.tsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";

export async function generateMetadata({ params }) {
    const { id } = await params;
    const product = await getProduct(id);

    const ogImageUrl = generateSignedOgUrl({
        template: "ecommerce",
        title: product.name,
        price: product.price,
        image: product.image,
    });

    return {
        openGraph: {
            title: product.name,
            description: product.description,
            images: [{ url: ogImageUrl, width: 1200, height: 630 }],
            type: "product",
        },
    };
}

Profil Pengguna (Template Blog)

FastOG tidak memiliki template profile — gunakan blog untuk kartu bergaya profil, dengan mengirimkan nama pengguna sebagai title, bio sebagai subtitle, dan nama sebagai author.

typescript
// app/users/[username]/page.tsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";

export async function generateMetadata({ params }) {
    const { username } = await params;
    const user = await getUser(username);

    const ogImageUrl = generateSignedOgUrl({
        template: "blog",
        title: user.name,
        subtitle: user.bio,
        author: user.name,
    });

    return {
        openGraph: {
            title: `${user.name} - Profile`,
            description: user.bio,
            images: [{ url: ogImageUrl, width: 1200, height: 630 }],
            type: "profile",
        },
    };
}

Kesalahan Umum

Menandatangani Byte yang Berbeda dari yang Dikirim

Tanda tangan mencakup GET/api/v1/og ditambah baris baru serta kueri kanonik — pasangan enc(key)=enc(value) yang diurutkan dari setiap parameter kecuali s, termasuk key. Bangun URL akhir dari pasangan terenkode yang sama tersebut, atau server akan mengembalikan 401 invalid_signature.

Mengekspos Rahasia HMAC dalam Kode Klien

❌ Salah:

javascript
// In client component
const ogUrl = generateSignedOgUrl(params, {
    hmacSecret: process.env.NEXT_PUBLIC_HMAC_SECRET,
});

✅ Benar:

javascript
// In server component or API route (never expose to client)
export async function generateMetadata() {
    const ogUrl = generateSignedOgUrl(params);
}

Referensi API Lengkap

Coba gratis — tanpa perlu mendaftar

Pratinjau dan uji gambar OG dinamis dalam hitungan detik.

Buka Penguji Gambar OG Gratis

A BeCaSimulations site