FastOG SDK – Letöltés és használat

Nyelvenként egy fájl, nulla függőség, csomagkezelő nem szükséges. Töltse le alább (vagy húzza be a curl-ból a CDN-ünkről), és másolja a projektjébe (csak szerveroldalon). Itt v1-esként tartjuk karban – amikor a szerződés változik, ezt az oldalt és a letölthető fájlokat együtt frissítjük. A teljes aláírási szerződéshez és a kézzel készített implementációkhoz bármely nyelven lásd az Agent & LLM integráció oldalt.

Letöltés

Válasszon nyelvet, és kattintson a letöltés gombra (vagy jobb gombbal → Mentés másként):

Ezek a hivatkozások a /sdk/<file> címet érik el, amely letöltésként szolgálja ki a fájlt – vagy használhatja a curl -O https://fastog.com/sdk/<file> parancsot, ha a parancssort részesíti előnyben.

A Vue, Next.js, Astro és Express Node-on fut – ugyanazokat a tesztelt aláírófájlokat (signer files) használják (CommonJS az Expresshez, ESM a többihez); csak a használati útmutató/README különbözik. Az egyes keretrendszerek sdk/<name>/README.md fájlja mutatja a pontos integrációt.

Minden fájl a teljes SDK-t tartalmazza. Másolja be a projektjébe, require/import, és kész.

Használat

Node.js

const { ogImageUrl } = require("./fastog.js");
const url = ogImageUrl(
    {
        template: "blog",
        title: "Hello World",
        features: ["Free shipping", "30-day returns"],
    },
    { key: process.env.FASTOG_API_KEY, secret: process.env.FASTOG_HMAC_SECRET },
);

SvelteKit (a +page.server.js / +layout.server.js mappában)

import { ogImageUrl } from "$lib/fastog.js";
const url = ogImageUrl(params, {
    key: process.env.FASTOG_API_KEY,
    secret: process.env.FASTOG_HMAC_SECRET,
});

PHP

use FastOg\FastOg;
$url = FastOg::signedUrl($params, getenv('FASTOG_API_KEY'), getenv('FASTOG_HMAC_SECRET'));

Ruby / Rails

url = FastOg.signed_url(params, ENV.fetch("FASTOG_API_KEY"), ENV.fetch("FASTOG_HMAC_SECRET"))

Python (Django / FastAPI / Flask)

import fastog
url = fastog.signed_url(params, os.environ["FASTOG_API_KEY"], os.environ["FASTOG_HMAC_SECRET"])

Go

url := fastog.SignedURL(params, os.Getenv("FASTOG_API_KEY"), os.Getenv("FASTOG_HMAC_SECRET"))

Express / Next.js / Astro / Vue (Node) – importálja az aláírót (signer), hívja meg a ogImageUrl(params, { key, secret })-t a szerverkódban, és jelenítse meg az URL-t a head szekcióban. Lásd az egyes keretrendszerek sdk/<name>/README.md dokumentációját.

Helyezze a url-t a <meta property="og:image">-be. A keresőrobotok lekérdezik – él-cache-elve, egy renderelés egyedi képenként.

Verziózás

Ez a v1, és helyben karbantartott. Amikor a szerződés változik, a fájlokat és ezt az oldalt együtt léptetjük (v2, v3, …) — Ön újraletöltéssel frissít. Nincs csomagregisztrációs szinkronizálás, nincs semver-formaság, nincs többcsomagos eltérés.

Működése

canonical = sorted enc(key)=enc(value) pairs of every param except `s`, including `key`
message   = "GET/api/v1/og" + "\n" + canonical
signature = hex(HMAC-SHA256(message, secret))

• A paraméterek bármilyen módosítása érvényteleníti az aláírást → 401, nincs renderelés, nincs kvótaszámítás.
• Azonos paraméterek → azonos URL → örökre gyorsítótárazható a peremhálózaton (edge).
• A tömbparaméterek (features) key[]= / key[0]= formátumban kerülnek kibocsátásra, így a szerver helyesen dekódolja őket.
• Visszavonás a kulcs titkos részének (secret) újragenerálásával történik.

Ellenőrzés

Minden SDK ugyanazzal a referenciavektorral (golden vector) van tesztelve, amelyet a FastOG szerver állít elő:

canonical = features=30-day%20returns&features=Free%20shipping&key=sk_test123&template=blog&title=Hello%20World
signature = a79232b15b45002aee76174f542e0a661b37cb1259df01e263c952ca4052a54d

Ha az Ön példánya ugyanezt az aláírást állítja elő ezekhez a paraméterekhez, a szerver elfogadja az Ön URL-jeit.

Biztonság

• A secret kizárólag szerveroldali — soha ne kerüljön a böngészőbe, és soha ne szerepeljen nyilvános CDN-szkriptben.
• A key nyilvános (megjelenik az URL-ekben) — ez elvárt működés.
• A szerveren írja alá; a FastOG URL-t ágyazza be, nem a titkos kulcsot.