Téma

OG obrázky v Astru

Generujte OG obrázky v Astru pomocí FastOG API — s předplatným Dynamic API (vytvořte si API klíč v dashboardu), na bázi předplatného, zabezpečené HMAC. Tento průvodce vám ukáže, jak vytvořit nástroj pro podepisování (signer) pro HMAC-podepsané URL adresy OG obrázků a dynamicky vykreslovat Open Graph obrázky za běhu. Před integrací si vyzkoušejte bezplatný tester OG obrázků (Free OG Image Tester) pro náhled.

Rychlý start

1. Vytvoření nástroje pro podepisování (signer)

javascript
// src/lib/og-image-signer.js
import crypto from "node:crypto";

export function generateSignedOgUrl(params, options = {}) {
    const {
        baseUrl = "https://fastog.com/api/v1/og",
        apiKey = import.meta.env.FASTOG_API_KEY,
        hmacSecret = import.meta.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. Proměnné prostředí

bash
# .env
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here

Blogový příspěvek

astro
---
// src/pages/blog/[slug].astro
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

const post = await getPost(Astro.params.slug);

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

<html>
    <head>
        <title>{post.title}</title>
        <meta property="og:image" content={ogImageUrl} />
        <meta property="og:title" content={post.title} />
        <meta property="og:description" content={post.excerpt} />
    </head>
    <body>
        <article>
            <h1>{post.title}</h1>
            <p>{post.excerpt}</p>
        </article>
    </body>
</html>

Content Collections (Kolekce obsahu)

javascript
// src/content/config.ts
import { defineCollection, z } from "astro:content";

const blog = defineCollection({
    type: "content",
    schema: z.object({
        title: z.string(),
        excerpt: z.string(),
        author: z.string(),
        date: z.date(),
    }),
});

export const collections = { blog };
astro
---
// src/pages/blog/[slug].astro
import { getCollection } from "astro:content";
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

const post = (await getCollection("blog")).find(
    (entry) => entry.slug === Astro.params.slug
);

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

<html>
    <head>
        <title>{post.data.title}</title>
        <meta property="og:image" content={ogImageUrl} />
        <meta property="og:title" content={post.data.title} />
        <meta property="og:description" content={post.data.excerpt} />
    </head>
    <body>
        <article>
            <h1>{post.data.title}</h1>
            <p>{post.data.excerpt}</p>
        </article>
    </body>
</html>

Příklad e-commerce

astro
---
// src/pages/products/[id].astro
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

const product = await getProduct(Astro.params.id);

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

<html>
    <head>
        <meta property="og:image" content={ogImageUrl} />
        <meta property="og:title" content={product.name} />
    </head>
    <body>
        <h1>{product.name}</h1>
        <p>{product.price}</p>
    </body>
</html>

Uživatelský profil (šablona blogu)

FastOG nemá profile šablonu — pro kartu ve stylu profilu použijte blog, přičemž jméno uživatele předáte jako title, bio jako subtitle a jméno jako author.

astro
---
// src/pages/users/[username].astro
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

const user = await getUser(Astro.params.username);

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

<html>
    <head>
        <meta property="og:image" content={ogImageUrl} />
        <meta property="og:title" content={`${user.name} - Profile`} />
    </head>
    <body>
        <h1>{user.name}</h1>
        <p>{user.bio}</p>
    </body>
</html>

API Endpoint

javascript
// src/pages/api/og.js
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

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

    if (!title) {
        return new Response(JSON.stringify({ error: "Missing title" }), {
            status: 400,
            headers: { "Content-Type": "application/json" },
        });
    }

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

    return new Response(JSON.stringify({ ogImageUrl }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
    });
}

Frameworkové komponenty

Astro podporuje React, Vue, Svelte a další. Podepisování vždy probíhá v .astro frontmatter (na straně serveru):

astro
---
// src/pages/blog/[slug].astro
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";
import BlogPost from "../../components/BlogPost.svelte";

const post = await getPost(Astro.params.slug);
const ogImageUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
});
---

<html>
    <head>
        <meta property="og:image" content={ogImageUrl} />
    </head>
    <body>
        <BlogPost client:load {post} />
    </body>
</html>

Časté chyby

Podepisování na straně klienta

Nikdy nepodepisujte OG URL v JavaScriptu na straně klienta.

❌ Špatně:

astro
<script>
    // Runs in browser — secret exposed!
    const ogUrl = generateSignedOgUrl({ title: "Test" });
</script>

✅ Správně:

astro
---
// Runs at build/SSR time — secret safe
const ogImageUrl = generateSignedOgUrl({ title: post.title });
---

Podepisování jiných bajtů, než které odesíláte

Podpis pokrývá GET/api/v1/og plus nový řádek plus kanonický dotaz — seřazené enc(key)=enc(value) páry všech parametrů kromě s, včetně key. Sestavte finální URL ze stejných zakódovaných párů, jinak server vrátí 401 invalid_signature.

Úplný referenční přehled API

Vyzkoušejte zdarma – bez registrace

Náhled a testování dynamických OG obrázků během pár sekund.

Otevřít bezplatný tester OG obrázků

A BeCaSimulations site