كل المستندات

تثبيت Web SDK وCDN

ثبّت حزمة المتصفح عبر CDN أو الاستضافة الذاتية وتحقق من الإرسال.

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

تثبيت Web SDK

حمّل SDK المتصفح عبر وسم script من CDN الرسمي لنيزا، أو من أصل الإصدار. أكّد نقطة النهاية ونمط المصادقة مع نشرك (مرجع API → Web SDK).

1. وسم script — CDN نيزا (موصى به)

تُخدم الملفات من sdk.naiza.ai (CDN مخصص مدعوم بـ GCS). ثبّت إصدارًا محددًا لاستقرار الإنتاج. مسار latest يشير دائمًا لأحدث إصدار.

CDN
<!-- إصدار مثبت (موصى به للإنتاج) -->
<script
  defer
  src="https://sdk.naiza.ai/v0.9.0/naizawebsdk.umd.js"
  crossorigin="anonymous"
></script>

<!-- أحدث دائمًا (مناسب للتطوير / staging) -->
<script defer src="https://sdk.naiza.ai/latest/naizawebsdk.umd.js"></script>

استخدم defer ليبدأ التنفيذ بعد تحليل HTML. حزمة UMD تعرض NaizaWebSdk على window.

Init
<script defer src="https://sdk.naiza.ai/v0.9.0/naizawebsdk.umd.js"></script>
<script>
  async function boot() {
    await NaizaWebSdk.init({
      token: "<MINTED_WEBSDK_JWT>",
      sdkSessionId: "ws_checkout_123",
      endpoint: "https://api.naiza.ai/api/v1/collect",
    });
  }
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", boot);
  } else {
    boot();
  }
</script>

المسار القياسي /api/v1/collect يستخدم Authorization: Bearer مع JWT قصير العمر يُصدر من الخادم عبر POST /api/v1/websdk/tokens.

2. تنزيل مباشر (استضافة ذاتية)

نزّل الحزمة من صفحة إصدارات GitHub واستضفها بنفسك إن احتجت تقديمها من نطاقك.

Download
# تنزيل إصدار محدد
curl -L https://github.com/limazifyLab/naizaWebSDK/releases/download/v0.9.0/naizawebsdk.umd.js \
  -o naizawebsdk.umd.js

3. الخصوصية وأخذ العينات

  • consent: false — لا تُرسل طلبات شبكة (GDPR opt-out). يستمر الجمع المحلي إن مُنحت الموافقة لاحقًا.
  • sampleRate — كسر اختياري من 0–1 لتقليل حجم الرفع. الدُفعات المكبوتة تُهمل.
  • إيقاف جامع معيّن عبر disabledCollectors أو collectorConfig.

4. التحقق من أصل آخر

  1. استخدم صفحة HTML في staging أو نشرًا ثابتًا مؤقتًا.
  2. حمّل عنوان CDN مثبت، وافتح DevTools → Network وتأكد أن POST يعيد 2xx مع Authorization: Bearer.
  3. بدّل consent: false وتأكد من عدم وجود طلبات لمضيف الاستقبال.

يتضمن مستودع SDK ملف examples/cdn-smoke-test.html لفحوصات سريعة من طرف إلى طرف.

5. CDN والإصدارات

كل إصدار مُعلَّم في مستودع naizaWebSDK ينشر تلقائيًا حزمة UMD إلى sdk.naiza.ai/v{VERSION}/. عناوين الإصدارات ثابتة ومخزَّنة دائمًا. مسار latest/ يُحدَّث مع كل إصدار وبـ TTL قصير (5 دقائق). راجع sdk.naiza.ai/manifest.json للإصدارات المتاحة.