SDK

Markdown

بالنسبة للاستخدام على الويب، الطريقة الموصى بها هي استخدام Unico SDK للأسباب التالية:

• أمان أعلى؛
• تجربة متكاملة مع تدفقك؛
• معدل تحويل أعلى عند استخدام SDK؛
• تنفيذ أسهل.

تحذير

قد يؤدي استخدام عمليات تكامل لا تلتزم بالمعايير الموضحة في هذه الوثائق إلى حدوث اضطرابات غير متوقعة في وظائف النظام، لن يتم تغطيتها أو دعمها من قبل التحقق من البطاقة غير الحاضرة.

على سبيل المثال: تنفيذ Unico عبر iFrame داخل webview، أو تنفيذ iFrame من خلال وسم HTML، وما إلى ذلك.

إرشادات عامة

لتحسين أداء عمليتك، وزيادة معدلات التحويل، وتوفير تجربة مستخدم أكثر سلاسة، من الإلزامي تنفيذ Unico SDK في وضع ملء الشاشة (full-screen) في تطبيقك.

كيفية البدء

لاستخدام التحقق من البطاقة غير الحاضرة من خلال SDK الخاص بالتحقق من البطاقة غير الحاضرة، الخطوة الأولى هي تسجيل النطاقات (domains) التي سيتم استخدامها كمضيفات (hosts) لعرض تجربة رحلة المستخدم.

خطر

أبلغ الشخص المسؤول عن مشروع التكامل الخاص بك أو فريق دعم Unico لإجراء هذا الإعداد.

للبدء في استخدام SDK، يجب أن نبدأ بتثبيت Unico web SDK:

npm install unico-journey-sdk

سابقًا idpay-b2b-sdk

كانت هذه الحزمة تُنشر سابقًا باسم idpay-b2b-sdk. إنها نفس SDK باسم جديد، وتتبع نفس خط الإصدارات. تُنشر الإصدارات 2.3.0 والأحدث فقط باسم unico-journey-sdk؛ أما الإصدارات الأقدم فتظل متاحة تحت الاسم السابق idpay-b2b-sdk.

نصيحة

عند تثبيت حزمة Unico SDK، انشرها دون تحديد الإصدار الذي تستخدمه حتى يقوم مدير التبعيات (dependency manager) الخاص بك دائمًا بتحديث الإصدارات الفرعية (minors) والتصحيحات (patches) إلى أحدث إصدار.

للاطلاع على الإصدارات السابقة، انتقل إلى npmjs.com/package/idpay-b2b-sdk.

الطرق المتاحة

init(options)

تتيح هذه الطريقة (method) تهيئة SDK بغض النظر عن معرّف المعاملة، مما يجعل تجربة المستخدم النهائي أكثر سلاسة. وذلك لأنه عندما يصبح معرّف المعاملة والرمز (token) متاحين، يكون التطبيق قد تم تحميله مسبقًا (pre-loaded) بالفعل من خلال هذه الطريقة. إذا لم يتم استدعاء هذه الطريقة مباشرة من قبل التطبيق، فسيواجه المستخدم النهائي وقت تحميل طويل عند فتح SDK للمرة الأولى.

المعاملات (Parameters):

• options — يستقبل كائنًا (object) بخصائص الإعداد:
  • type — نوع التدفق الذي سيتم تهيئته. نوفر حاليًا النوع IFRAME. بالنسبة للتطبيقات الجديدة، نوصي باستخدام النوع IFRAME، الذي يجعل تجربة المستخدم النهائي أكثر سلاسة وأقل احتكاكًا، حيث يتجنب الحاجة لمغادرة شاشة الدفع (checkout)، ويمكن تحميل التجربة مسبقًا (preloaded).

import { IDPaySDK } from "unico-journey-sdk";

IDPaySDK.init({
  type: 'IFRAME',
  env: 'uat' // مطلوب فقط لبيئة الاختبار.
});

open({ transactionId, token, onFinish? })

تفتح هذه الطريقة (method) تجربة التحقق من البطاقة غير الحاضرة وفقًا لنوع التدفق الذي تم اختياره مسبقًا في دالة التهيئة (initialization function). بالنسبة لتدفق REDIRECT، تقوم هذه الدالة بإعادة توجيه بسيطة إلى مسار تدفق الالتقاط الخاص بالتحقق من البطاقة غير الحاضرة. بالنسبة لتدفق IFRAME، تعرض هذه الدالة الـ iframe المحمَّل مسبقًا وتبدأ تدفق تبادل الرسائل بين صفحة العميل وتجربة التحقق من البطاقة غير الحاضرة.

المعاملات (Parameters):

• options — يستقبل كائنًا (object) بخصائص الإعداد:
  • transactionId — يستقبل معرّف المعاملة التي تم إنشاؤها. هذا المعرّف مهم للحصول على تفاصيل المعاملة وإكمال التدفق بشكل صحيح (يمكن الحصول عليه أثناء إنشاء المعاملة عبر واجهة برمجة التطبيقات API).
  • token — يستقبل الرمز (token) الخاص بالمعاملة التي تم إنشاؤها. هذا الرمز مهم لمصادقة المعاملة وضمان استخدامه من قبل النطاقات (domains) المصرح لها فقط (يمكن الحصول عليه أثناء إنشاء المعاملة عبر واجهة برمجة التطبيقات API).
  • onFinish(transaction, type) (اختياري) — يستقبل دالة استدعاء (callback) سيتم تنفيذها في نهاية تدفق الالتقاط الخاص بالتحقق من البطاقة غير الحاضرة، وتمرر وسيطين (arguments): كائن المعاملة ({ captureConcluded, concluded, id })، ونوع الاستجابة — FINISH للحالات التي اكتمل فيها التدفق بنجاح، أو ERROR للحالات التي تم فيها مقاطعة التدفق بسبب خطأ. في حالات حدوث خطأ في التدفق، لن تتغير حالة المعاملة، ولن يتم تشغيل استدعاء (callback) عبر webhook، إن كان مُعدًا.

const transactionId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

const transaction = {
  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  concluded: true,
  captureConcluded: true
};

const onFinish = (transaction, type) => {
  console.log('response', transaction, type);
}

IDPaySDK.open({
  transactionId,
  token,
  onFinish
});

// يمكنك أيضًا إغلاق SDK بشكل صريح باستخدام الطريقة أدناه
IDPaySDK.close();

الأمان

بعد تحليل دقيق للاحتياجات والتحديات التي نواجهها، قررنا اعتماد حل قائم على iFrames مع رموز مصادقة (authentication tokens) بدلاً من تنفيذ سياسة أمان المحتوى (Content Security Policy - CSP). كان هذا القرار مدفوعًا باعتبارات عديدة تتعلق بالأمان والمرونة المطلوبة لتلبية متطلبات عملائنا.

السياق والتحديات المتعلقة بـ CSP

تُعد سياسة أمان المحتوى (Content Security Policy - CSP) أداة قوية لحماية تطبيقات الويب من مختلف أنواع الهجمات، مثل البرمجة النصية عبر المواقع (Cross-Site Scripting - XSS) وحقن الشيفرة (code injection). ومع ذلك، عند إعداد سياسة CSP، من الضروري تحديد قائمة صارمة بالنطاقات (domains) الموثوقة. تعمل هذه الطريقة بشكل جيد عندما تكون النطاقات ثابتة ويمكن التنبؤ بها. ومع ذلك، بالنسبة لعملائنا الذين غالبًا ما يستخدمون نطاقات ديناميكية ومتغيرة، يمثل هذا الإعداد الصارم تحديات كبيرة.

الثغرات الأمنية مع النطاقات الديناميكية

تشكل النطاقات الديناميكية خطرًا أمنيًا كبيرًا عند استخدام CSP. عندما يكون لدى العميل نطاقات تتغير بشكل متكرر أو يتم إنشاؤها ديناميكيًا، سيكون من الضروري تحديث سياسة CSP باستمرار لتشمل هذه النطاقات الجديدة. لا يزيد هذا من جهد الصيانة فحسب، بل يعرّض أيضًا النطاقات التي تنطبق عليها سياسة CSP. كل نطاق يُضاف إلى سياسة CSP يمثل نقطة ضعف محتملة إذا لم تتم إدارته بشكل صحيح.

الحل باستخدام iFrame ورمز المصادقة (Auth Token)

للتخفيف من هذه المخاطر وتلبية المرونة التي يطلبها عملاؤنا، اخترنا استخدام iFrames مقترنة برموز المصادقة (authentication tokens). يوفر هذا الحل طبقة إضافية من الأمان ويلغي الحاجة إلى كشف أو إدارة قائمة واسعة وديناميكية من النطاقات.

كيف يعمل ذلك

• مصادقة آمنة: يتم تحميل كل iframe برمز مصادقة فريد لكل معاملة، مما يضمن أن المستخدمين المصرح لهم فقط يمكنهم الوصول إلى المحتوى. يتم التحقق من هذا الرمز في الوقت الفعلي، مما يوفر طبقة إضافية من الأمان والتحكم.
• عزل المحتوى: يتيح استخدام iFrames عزل المحتوى في سياق (context) منفصل، مما يقلل من خطر التداخل بين مصادر (origins) مختلفة ويخفف من الهجمات المحتملة.
• المرونة مع النطاقات الديناميكية: من خلال عدم الاعتماد على سياسة CSP ثابتة، يتكيف حلنا بسهولة مع النطاقات الديناميكية للعملاء دون الحاجة إلى تحديثات مستمرة لسياسات الأمان.