Θέμα

Εικόνες OG σε JavaScript

Δημιουργήστε εικόνες og:image σε JavaScript με το FastOG API — με συνδρομή Dynamic API (δημιουργήστε το κλειδί API σας στον πίνακα ελέγχου), βάσει συνδρομής, με ασφάλεια HMAC. Αυτός ο οδηγός σάς δείχνει πώς να δημιουργήσετε ένα βοηθητικό εργαλείο υπογραφής (signer utility) για διευθύνσεις URL εικόνων OG με υπογραφή HMAC και να αποδίδετε δυναμικές εικόνες Open Graph εν κινήσει. Δοκιμάστε το Δωρεάν Εργαλείο Δοκιμής Εικόνων OG για προεπισκόπηση πριν τη δημοσίευση.

Γρήγορη Εκκίνηση

Στόχος: Δημιουργία υπογεγραμμένου URL εικόνας OG σε 5 λεπτά.

Βήμα 1: Εγκατάσταση Εξαρτήσεων

bash

npm install crypto  # Built-in, no install needed

Βήμα 2: Δημιουργία Βοηθητικής Συνάρτησης Υπογραφής

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

Βήμα 3: Χρήση στην Εφαρμογή σας

javascript

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

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

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

    return {
        openGraph: {
            images: [ogImageUrl],
        },
    };
}

Βήμα 4: Δοκιμή

Η συνάρτηση υπογραφής είναι μια ενότητα ES (import/export), οπότε χρησιμοποιήστε δυναμικό import():

bash

node -e "
import('./lib/og-image-signer.js').then(({ generateSignedOgUrl }) => {
    console.log(generateSignedOgUrl({ title: 'Test' }));
});
"

Next.js App Router

Μοτίβο 1: Metadata API (Προτεινόμενο)

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,
        // Optional: customize colors
        theme: "indigo",
    });

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

Μοτίβο 2: Διαμεσολάβηση μέσω API Route

Χρησιμοποιήστε αυτό το μοτίβο αν θέλετε να αποθηκεύσετε προσωρινά τις εικόνες OG ή να προσθέσετε προσαρμοσμένη λογική.

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

        // Generate signed URL
        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 },
        );
    }
}

Χρήση:

typescript

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

Μοτίβο 3: Άμεση χρήση σε Server Component

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

Next.js Pages Router

typescript

// pages/blog/[slug].tsx
import { generateSignedOgUrl } from '@/lib/og-image-signer';
import { GetStaticProps, GetStaticPaths } from 'next';

interface BlogPostProps {
    post: Post;
    ogImageUrl: string;
}

export default function BlogPost({ post, ogImageUrl }: BlogPostProps) {
    return (
        <>
            <Head>
                <meta property="og:image" content={ogImageUrl} />
                <meta property="og:title" content={post.title} />
                <meta property="og:description" content={post.excerpt} />
            </Head>
            <article>
                <h1>{post.title}</h1>
                <p>{post.excerpt}</p>
            </article>
        </>
    );
}

export async function getStaticPaths() {
    // Generate paths...
}

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

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

    return {
        props: {
            post,
            ogImageUrl,
        },
    };
}

Express.js Backend

Ρύθμιση

bash

npm install express crypto

Υλοποίηση

javascript

// app.js
import express from "express";
import crypto from "crypto";
import { URL } from "url";

const app = express();

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

// Blog post route
app.get("/blog/:slug", async (req, res) => {
    const post = await getPost(req.params.slug);

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

    res.render("blog/post", {
        post,
        ogImageUrl,
    });
});

// API endpoint for dynamic OG images
app.get("/api/og", (req, res) => {
    const { title, template = "default" } = req.query;

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

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

    res.json({ ogImageUrl });
});

app.listen(3000, () => {
    console.log("Server running on port 3000");
});

Πρότυπο EJS

ejs

<!-- views/blog/post.ejs -->
<!DOCTYPE html>
<html>
<head>
    <meta property="og:image" content="<%= ogImageUrl %>" />
    <meta property="og:title" content="<%= post.title %>" />
    <meta property="og:description" content="<%= post.excerpt %>" />
</head>
<body>
    <h1><%= post.title %></h1>
</body>
</html>

Vanilla Node.js

javascript

// og-signer.js
const crypto = require("crypto");
const { URL } = require("url");

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

module.exports = { generateSignedOgUrl };

Χρήση:

javascript

// index.js
const { generateSignedOgUrl } = require("./og-signer");

const ogUrl = generateSignedOgUrl({
    template: "blog",
    title: "My Blog Post",
});

console.log("OG Image URL:", ogUrl);

Πρότυπα Ενσωμάτωσης Frontend

Πρότυπο 1: Δημιουργία Στατικού Ιστότοπου (SSG)

Κατάλληλο για: Αναρτήσεις ιστολογίου, σελίδες προϊόντων, περιεχόμενο που δεν αλλάζει συχνά.

typescript

// Generate at build time
export async function generateStaticParams() {
    const posts = await getAllPosts();
    return posts.map((post) => ({ slug: post.slug }));
}

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

    return {
        openGraph: {
            images: [generateSignedOgUrl({ title: post.title })],
        },
    };
}

Πρότυπο 2: Απόδοση από την Πλευρά του Διακομιστή (SSR)

Κατάλληλο για: Δυναμικό περιεχόμενο, σελίδες εξατομικευμένες για τον χρήστη.

typescript

export default async function Page({ params }) {
    const data = await fetchData(params.id);
    const ogImageUrl = generateSignedOgUrl({ title: data.title });

    return (
        <>
            <Head>
                <meta property="og:image" content={ogImageUrl} />
            </Head>
            <Content data={data} />
        </>
    );
}

Πρότυπο 3: Εναλλακτική από την Πλευρά του Πελάτη

Όταν η δημιουργία από την πλευρά του διακομιστή δεν είναι εφικτή.

typescript

'use client';

import { useEffect, useState } from 'react';

export default function ShareButtons({ post }) {
    const [ogImageUrl, setOgImageUrl] = useState<string | null>(null);

    useEffect(() => {
        // Fetch from your API that generates signed URLs
        fetch(`/api/og?title=${encodeURIComponent(post.title)}`)
            .then(res => res.json())
            .then(data => setOgImageUrl(data.ogImageUrl));
    }, [post.title]);

    const shareUrl = ogImageUrl || '/fallback-og.png';

    return (
        <div>
            <button onClick={() => shareToTwitter(shareUrl)}>
                Share on Twitter
            </button>
        </div>
    );
}

⚠️ Προειδοποίηση: Η δημιουργία από την πλευρά του πελάτη σημαίνει ότι οι ανιχνευτές κοινωνικών δικτύων δεν θα δουν τη δυναμική εικόνα OG. Χρησιμοποιήστε SSR/SSG όταν είναι δυνατόν.

Δοκιμές & Αποσφαλμάτωση

Μοναδιαίες Δοκιμές

javascript

// __tests__/og-image-signer.test.js
import { generateSignedOgUrl } from "../lib/og-image-signer";

describe("generateSignedOgUrl", () => {
    const mockParams = {
        title: "Test Post",
        template: "blog",
    };

    const mockOptions = {
        apiKey: "sk_test1234567890",
        hmacSecret: "a".repeat(64),
    };

    it("generates a valid URL", () => {
        const url = generateSignedOgUrl(mockParams, mockOptions);
        expect(url).toMatch(/^https:\/\/fastog\.com\/api\/v1\/og\?/);
        expect(url).toContain("key=sk_test");
        expect(url).toContain("s=");
    });

    it("includes all params", () => {
        const url = generateSignedOgUrl(mockParams, mockOptions);
        const parsed = new URL(url);
        expect(parsed.searchParams.get("title")).toBe("Test Post");
        expect(parsed.searchParams.get("template")).toBe("blog");
    });

    it("throws without API key", () => {
        expect(() => generateSignedOgUrl(mockParams, {})).toThrow();
    });
});

Χειροκίνητες Δοκιμές

bash

# 1. Generate URL (ES module — use dynamic import)
node -e "
import('./lib/og-image-signer.js').then(({ generateSignedOgUrl }) => {
    const url = generateSignedOgUrl({ title: 'Test' });
    console.log(url);
});
"

# 2. Test with curl
curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<sig>"

# 3. Check response headers
curl -I "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<sig>"

Λειτουργία Αποσφαλμάτωσης

javascript

function generateSignedOgUrl(params, options = {}) {
    const debug = options.debug || process.env.DEBUG_OG === "true";

    // ... existing code ...

    if (debug) {
        console.log("OG URL Debug:", {
            baseUrl,
            canonical,
            apiKey,
            signature,
            finalUrl: url.toString(),
        });
    }

    return url.toString();
}

Συνήθη Λάθη

1. Έκθεση του HMAC Secret σε Κώδικα Πελάτη

❌ Λάθος:

javascript

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

✅ Σωστό:

javascript

// In server component or API route
export async function generateMetadata() {
    const ogUrl = generateSignedOgUrl(params);
    // ...
}

2. Μη Διαχείριση της Κωδικοποίησης URL

❌ Λάθος:

javascript

const url = `${baseUrl}?title=${params.title}&key=${apiKey}`;

✅ Σωστό:

javascript

const url = new URL(baseUrl);
url.searchParams.set("title", params.title);
url.searchParams.set("key", apiKey);

3. Υπογραφή Διαφορετικών Bytes από Αυτά που Αποστέλλονται

Η υπογραφή καλύπτει το GET/api/v1/og συν ένα χαρακτήρα νέας γραμμής συν το κανονικό query — τα ταξινομημένα ζεύγη enc(key)=enc(value) κάθε παραμέτρου εκτός από το s, συμπεριλαμβανομένου του key. Δημιουργήστε το τελικό URL από αυτά τα ίδια κωδικοποιημένα ζεύγη, διαφορετικά ο διακομιστής επιστρέφει 401 invalid_signature.

Μεταβλητές Περιβάλλοντος

bash

# .env.local
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here
FASTOG_BASE_URL=https://fastog.com/api/v1/og

typescript

// lib/env.ts
import { z } from "zod";

const envSchema = z.object({
    FASTOG_API_KEY: z.string().startsWith("sk_"),
    FASTOG_HMAC_SECRET: z.string().length(64),
    FASTOG_BASE_URL: z
        .string()
        .url()
        .optional()
        .default("https://fastog.com/api/v1/og"),
});

export const env = envSchema.parse(process.env);

Επόμενα Βήματα

Εκμάθηση PHP
Εκμάθηση Python
Αναφορά API
Οδηγός Υπογραφής HMAC

Πλήρης Αναφορά API

Εκμάθηση React
Εκμάθηση SvelteKit
Εκμάθηση Vue/Nuxt
Εκμάθηση Astro
Γρήγορη εκκίνηση
SDK
Ενσωμάτωση πράκτορα
Τεκμηρίωση
Δωρεάν ελεγκτής εικόνων OG

Δοκιμάστε το δωρεάν — δεν απαιτείται εγγραφή

Προεπισκόπηση και δοκιμή δυναμικών εικόνων OG σε δευτερόλεπτα.

Ανοίξτε τον Δωρεάν Ελεγκτή Εικόνων OG

Εικόνες OG σε JavaScript

Πίνακας Περιεχομένων

Γρήγορη Εκκίνηση

Βήμα 1: Εγκατάσταση Εξαρτήσεων

Βήμα 2: Δημιουργία Βοηθητικής Συνάρτησης Υπογραφής

Βήμα 3: Χρήση στην Εφαρμογή σας

Βήμα 4: Δοκιμή

Next.js App Router

Μοτίβο 1: Metadata API (Προτεινόμενο)

Μοτίβο 2: Διαμεσολάβηση μέσω API Route

Μοτίβο 3: Άμεση χρήση σε Server Component

Next.js Pages Router

Express.js Backend

Ρύθμιση

Υλοποίηση

Πρότυπο EJS

Vanilla Node.js

Πρότυπα Ενσωμάτωσης Frontend

Πρότυπο 1: Δημιουργία Στατικού Ιστότοπου (SSG)

Πρότυπο 2: Απόδοση από την Πλευρά του Διακομιστή (SSR)

Πρότυπο 3: Εναλλακτική από την Πλευρά του Πελάτη

Δοκιμές & Αποσφαλμάτωση

Μοναδιαίες Δοκιμές

Χειροκίνητες Δοκιμές

Λειτουργία Αποσφαλμάτωσης

Συνήθη Λάθη

1. Έκθεση του HMAC Secret σε Κώδικα Πελάτη

2. Μη Διαχείριση της Κωδικοποίησης URL

3. Υπογραφή Διαφορετικών Bytes από Αυτά που Αποστέλλονται

Μεταβλητές Περιβάλλοντος

Επόμενα Βήματα

Πλήρης Αναφορά API

Σχετικά