FastOG SDK — Pobieranie i użycie

Jeden plik na język, zero zależności, bez menedżera pakietów. Pobierz go poniżej (lub curl z naszego CDN) i skopiuj do swojego projektu (tylko po stronie serwera). Utrzymywany jako v1 tutaj — gdy kontrakt się zmieni, aktualizujemy tę stronę oraz pliki do pobrania razem. Pełny kontrakt podpisywania oraz ręczne implementacje w dowolnym języku znajdziesz w Integracja agentów i LLM.

Pobieranie

Wybierz język i kliknij pobierz (lub kliknij prawym przyciskiem myszy → Zapisz jako):

Te linki prowadzą do /sdk/<file>, które serwuje plik jako pobieranie — lub użyj curl -O https://fastog.com/sdk/<file>, jeśli wolisz wiersz poleceń.

Vue, Next.js, Astro i Express działają na Node — współdzielą te same przetestowane pliki podpisujące (CommonJS dla Express, ESM dla pozostałych); różni się tylko użycie/README. sdk/<name>/README.md każdego frameworka pokazuje dokładną integrację.

Każdy plik to całe SDK. Skopiuj go do swojego projektu, require/import go, gotowe.

Zastosowanie

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 (w +page.server.js / +layout.server.js)

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) — zaimportuj funkcję podpisującą (signer), wywołaj ogImageUrl(params, { key, secret }) w kodzie serwera i wyrenderuj URL w sekcji head. Zobacz sdk/<name>/README.md dla każdego frameworka.

Wstaw url do <meta property="og:image">. Crawlery pobierają go metodą GET — cachowanie na brzegu sieci, jedno renderowanie na unikalny obraz.

Wersjonowanie

To jest wersja v1 i jest utrzymywana w miejscu. Gdy zmienia się kontrakt, aktualizujemy pliki oraz tę stronę razem (v2, v3, …) — aktualizujesz, pobierając je ponownie. Brak rejestru pakietów do synchronizacji, brak ceremonii semver, brak dryfu między pakietami.

Jak to działa

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

• Każda zmiana parametru unieważnia podpis → 401, brak renderowania, brak naliczania zapytań.
• Identyczne parametry → identyczny URL → możliwość cache'owania na brzegu sieci (edge) bezterminowo.
• Parametry tablicowe (features) są emitowane jako key[]= / key[0]=, aby serwer poprawnie je dekodował.
• Unieważnienie następuje przez rotację sekretu klucza.

Weryfikacja

Wszystkie SDK są testowane względem tego samego złotego wektora (golden vector) wygenerowanego przez serwer FastOG:

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

Jeśli Twoja kopia wygeneruje ten podpis dla tych parametrów, serwer zaakceptuje Twoje adresy URL.

Bezpieczeństwo

• secret jest tylko po stronie serwera — nigdy w przeglądarce, nigdy w publicznym skrypcie CDN.
• key jest publiczny (pojawia się w adresach URL) — to normalne.
• Podpisuj na swoim serwerze; to adres URL FastOG osadzasz, a nie sekret.