كل المستندات

تثبيت Web SDK وCDN

ثبّت حزمة نيزا للمتصفح من CDN أو من استضافتك الخاصة لجمع إشارات الجهاز واستخدامها في كشف الاحتيال عند الدخول والدفع.

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

تثبيت Web SDK

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

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

تُخدم الملفات من storage.googleapis.com/naiza-sdk-cdn (شبكة CDN مخصصة تعمل على GCS). استخدم رقم إصدار محددًا لضمان استقرار بيئة الإنتاج، أما مسار latest فيشير دائمًا إلى أحدث إصدار.

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

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

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

Init
<script defer src="https://storage.googleapis.com/naiza-sdk-cdn/v0.10.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. تنزيل مباشر (استضافة ذاتية)

نزّل الحزمة من ملف الحزمة واستضفها على خوادمك إذا احتجت تقديمها من نطاقك.

Download
# تنزيل إصدار محدد
curl -L https://storage.googleapis.com/naiza-sdk-cdn/v0.10.0/naizawebsdk.umd.js \
  -o naizawebsdk.umd.js

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

  • consent: false — لا تُرسَل أي طلبات عبر الشبكة (رفض الموافقة وفق GDPR). يستمر الجمع المحلي إن مُنحت الموافقة لاحقًا.
  • 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 لإجراء اختبار سريع شامل (end-to-end).

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

كل إصدار مُعلَّم في مستودع naizaWebSDK تُنشر حزمة UMD الخاصة به تلقائيًا إلى storage.googleapis.com/naiza-sdk-cdn/v{VERSION}/. عناوين الإصدارات ثابتة لا تتغير، وتُخزَّن مؤقتًا بشكل دائم. أما مسار latest/ فيُحدَّث مع كل إصدار، ومدة تخزينه المؤقت (TTL) قصيرة (5 دقائق). راجع storage.googleapis.com/naiza-sdk-cdn/manifest.json لمعرفة الإصدارات المتاحة.