FastOG SDK — Λήψη & Χρήση

Ένα αρχείο ανά γλώσσα, μηδενικές εξαρτήσεις, δεν απαιτείται διαχειριστής πακέτων. Κατεβάστε το παρακάτω (ή curl το από το CDN μας) και αντιγράψτε το στο έργο σας (μόνο για διακομιστή). Διατηρείται ως v1 εδώ — όταν αλλάξει η σύμβαση, ενημερώνουμε αυτή τη σελίδα και τα αρχεία λήψης μαζί. Για την πλήρη σύμβαση υπογραφής + υλοποιήσεις χειροποίητες σε οποιαδήποτε γλώσσα, δείτε Ενσωμάτωση Agent & LLM.

Λήψεις

Επιλέξτε μια γλώσσα και πατήστε λήψη (ή δεξί κλικ → Αποθήκευση ως):

Αυτοί οι σύνδεσμοι οδηγούν στο /sdk/<file>, το οποίο εξυπηρετεί το αρχείο ως λήψη — ή χρησιμοποιήστε το curl -O https://fastog.com/sdk/<file> αν προτιμάτε τη γραμμή εντολών.

Τα Vue, Next.js, Astro και Express τρέχουν σε Node — μοιράζονται τα ίδια δοκιμασμένα αρχεία υπογραφής (signer) (CommonJS για Express, ESM για τα υπόλοιπα)· μόνο η τεκμηρίωση χρήσης/README διαφέρει. Το 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 κάθε framework.

Τοποθετήστε το url μέσα στο <meta property="og:image">. Οι crawlers το λαμβάνουν μέσω GET — με caching στο edge, μία απόδοση ανά μοναδική εικόνα.

Έκδοση (Versioning)

Αυτή είναι η v1 και συντηρείται επιτόπου. Όταν αλλάζει το συμβόλαιο, αναβαθμίζουμε τα αρχεία μαζί με αυτή τη σελίδα (v2, v3, …) — εσείς ενημερώνεστε με επαναλήψη λήψης. Δεν υπάρχει μητρώο πακέτων για συγχρονισμό, ούτε διαδικασίες semver, ούτε αποκλίσεις μεταξύ πολλαπλών πακέτων.

Πώς λειτουργεί

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 → αποθηκεύσιμο στην άκρη επ' αόριστον.
• Οι παράμετροι πινάκων (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 είναι μόνο για τον διακομιστή — ποτέ στον browser, ποτέ σε δημόσιο script CDN.
• Το key είναι δημόσιο (εμφανίζεται σε URLs) — αυτό είναι αναμενόμενο.
• Υπογράψτε στον διακομιστή σας· το URL του FastOG είναι αυτό που ενσωματώνετε, όχι το μυστικό.