كل المستندات

واجهة Web SDK

نقاط نهاية حزمة المتصفح وجمع إشارات الجهاز.

تنزيل Markdown
الأدلةمرجع APIأمثلة الكودأفضل الممارسات

Web SDK

اجمع إشارات الجهاز والسلوك في المتصفح باستخدام رمز قصير العمر مرتبط بالجلسة والأصل.

أنماط النشر

الطريقةالمسارالاستخدام
POST/api/v1/websdk/tokensالخادم يصدر رمز SDK باستخدام x-api-key
POST/api/v1/collectالمسار القياسي: Bearer token وقرار متزامن
POST/api/v1/websdk/signalsإرسال دفعة إشارات باستخدام Bearer token

Mode A (canonical) — Mint + Bearer + /collect

POST /api/v1/websdk/tokens بمفتاح x-api-key من الخادم، ثم POST /api/v1/collect بـ Authorization: Bearer.

Mode B — Mint + Bearer + /websdk/signals

POST /api/v1/websdk/signals يستخدم Bearer أيضًا ويقبل غلاف websdk.v1؛ الاستجابة إقرار قائمة انتظار.

Mode C (legacy) — proxy /collect + x-api-key

بعض بوابات النشر المخصصة تبقي عنوان proxy يتوقع x-api-key من المتصفح. استخدمه فقط إذا كانت بيئتك المخصصة توثّقه صراحةً.

إصدار رمز SDK

Mint token request
POST /api/v1/websdk/tokens

{
  "sdkSessionId": "sdk_01HZ9XKPQR3N8T5VWMYJ4GE7D",
  "tenantSessionId": "sess_abc123",
  "origin": "https://app.example.com",
  "flow": "checkout",
  "userExternalId": "user_789"
}
Mint token response
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": "2026-04-16T10:45:00.000Z",
  "sdkSessionId": "sdk_01HZ9XKPQR3N8T5VWMYJ4GE7D"
}

إرسال الإشارات

Signals batch
POST /api/v1/websdk/signals
Authorization: Bearer <short-lived-sdk-token>

{
  "schemaVersion": "websdk.v1",
  "batchId": "01HZ9XKPQR3N8T5VWMYJ4GE7D",
  "sentAt": 1742126100000,
  "sdkSessionId": "sdk_01HZ9XKPQR3N8T5VWMYJ4GE7D",
  "signals": { "mouse_move_count": 42 }
}