FastOG SDK — التنزيل والاستخدام

ملف واحد لكل لغة، بدون أي تبعيات، ولا يتطلب مدير حزم. قم بتنزيله أدناه (أو curl من شبكة التوصيل لدينا) وانسخه إلى مشروعك (من جانب الخادم فقط). يتم الحفاظ عليه كـ v1 هنا — عندما يتغير العقد، نقوم بتحديث هذه الصفحة والملفات القابلة للتنزيل معًا. للحصول على عقد التوقيع الكامل + تطبيقات مكتوبة يدويًا بأي لغة، راجع تكامل الوكيل وLLM.

التنزيلات

اختر لغة واضغط على تنزيل (أو انقر بزر الفأرة الأيمن ثم اختر "حفظ باسم"):

تصل هذه الروابط إلى /sdk/<file>، الذي يقدّم الملف كتنزيل — أو استخدم curl -O https://fastog.com/sdk/<file> إذا كنت تفضّل سطر الأوامر.

Vue وNext.js وAstro وExpress تعمل على Node — وتشترك في نفس ملفات التوقيع المختبرة (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 }) في كود الخادم الخاص بك، ثم اعرض الرابط في وسم الرأس (head). راجع sdk/<name>/README.md الخاص بكل إطار عمل.

ضع url داخل <meta property="og:image">. ستقوم برامج الزحف (crawlers) بجلبه عبر طلب GET — مع تخزين مؤقت عند الحافة (edge-cached)، وعرض واحد لكل صورة فريدة.

الإصدارات

هذه هي النسخة 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، لا عرض، لا احتساب للحصة.
• معاملات متطابقة → رابط متطابق → قابل للتخزين المؤقت عند الحافة إلى الأبد.
• معاملات المصفوفات (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) — وهذا أمر متوقع.
• وقّع على خادمك؛ رابط FastOG هو ما تقوم بتضمينه، وليس السر.