FastOG SDK — завантаження та використання

Один файл на мову, без жодних залежностей, менеджер пакунків не потрібен. Завантажте його нижче (або curl з нашого CDN) і скопіюйте у свій проєкт (лише для серверної частини). Підтримується як v1 саме тут — коли контракт змінюється, ми оновлюємо цю сторінку та завантажувані файли разом. Повний контракт підписання та власноруч реалізовані варіанти будь-якою мовою дивіться у розділі Інтеграція агентів та LLM.

Завантаження

Оберіть мову та натисніть завантажити (або клацніть правою кнопкою миші → Зберегти як):

Ці посилання ведуть на /sdk/<file>, який віддає файл як завантаження — або скористайтеся curl -O https://fastog.com/sdk/<file>, якщо віддаєте перевагу командному рядку.

Vue, Next.js, Astro та Express працюють на Node — вони використовують ті самі перевірені файли підписувача (CommonJS для Express, ESM для решти); відрізняється лише документація з використання. У sdk/<name>/README.md кожного фреймворка показано точну інтеграцію.

Кожен файл — це повний SDK. Скопіюйте його у свій проєкт, виконайте require/import — і готово.

Використання

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 (у +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) — імпортуйте підписувач (signer), викличте ogImageUrl(params, { key, secret }) у серверному коді та відрендеріть URL у секції head. Дивіться sdk/<name>/README.md для кожної з фреймворків.

Додайте url у <meta property="og:image">. Краулери отримують його через GET — кешування на межі мережі, один рендер на унікальне зображення.

Версіонування

Це v1, і вона підтримується на цьому ж місці. Коли контракт змінюється, ми оновлюємо файли разом із цією сторінкою (v2, v3, …) — ви оновлюєтеся, повторно завантажуючи файли. Жодного реєстру пакетів для синхронізації, жодних семвер-церемоній, жодного розходження між пакетами.

Як це працює

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

• Будь-яка зміна параметра анулює підпис → 401, без рендерингу, без обліку квоти.
• Ідентичні параметри → ідентична URL-адреса → можливість кешування на межі мережі (edge) назавжди.
• Параметри-масиви (features) передаються як key[]= / key[0]=, щоб сервер декодував їх правильно.
• Відкликання здійснюється шляхом ротації секрету ключа.

Перевірка

Усі SDK тестуються на одному й тому ж еталонному векторі (golden vector), який генерує сервер FastOG:

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

Якщо ваша копія створює такий підпис для цих параметрів, сервер прийматиме ваші URL-адреси.

Безпека

• secret призначений лише для серверної частини — ніколи не використовуйте його в браузері чи в публічному CDN-скрипті.
• key є публічним (він з’являється в URL-адресах) — це нормально.
• Підписуйте запити на своєму сервері; у вбудований код потрапляє саме URL FastOG, а не секретний ключ.