تكامل تطبيق الويب

تغطي هذه الصفحة نهجَي التكامل من جانب العميل لعقد Web & SDK: إعادة توجيه المستخدم إلى رحلة مستضافة من Unico، وتضمين الرحلة عبر iFrame SDK.

إعادة توجيه المستخدم

بعد إنشاء العملية، تتضمن الاستجابة عنوان URL يشير إلى الرحلة المستضافة من Unico. استخدم هذا العنوان لنقل المستخدم إلى تجربة التقاط الصورة. هناك طريقتان لإدارة هذا الانتقال:

1. إعادة التوجيه القياسية

أعِد توجيه المستخدم مباشرةً إلى عنوان URL الخاص بالرحلة. عند إتمام المستخدم للعملية، تعيد Unico توجيهه إلى عنوان URL الذي حددته عند إنشاء العملية.

2. فتح نافذة جديدة باستخدام window.open()

افتح الرحلة في علامة تبويب جديدة بالمتصفح كي يبقى المستخدم في سياق منفصل. راقب تغيير عنوان URL إلى عنوان العودة الخاص بك وأغلق علامة التبويب عند اكتمال العملية.

للاطلاع على تفاصيل واجهة برمجة window.open()، راجع توثيق MDN.

iFrame

تحذير

قد تتسبب عمليات التكامل التي لا تتبع المعايير الواردة في هذا التوثيق في انقطاعات غير متوقعة، ولن تغطيها دعم Unico.

أمثلة على الأساليب غير المدعومة: تضمين SDK داخل WebView، أو تحميل iFrame مباشرةً عبر وسم HTML.

كيفية البدء

الخطوة 1 — التثبيت

يستخدم SDK الخاص بـ by Unico نفس الحزمة المستخدمة في IDPay:

npm install idpay-b2b-sdk

نصيحة

قم بالتثبيت دون تثبيت إصدار محدد كي يسحب مدير الحزم دائماً أحدث الإصدارات الثانوية والتصحيحية تلقائياً.

قبل البدء، سجّل نطاقاتك مع فريق دعم Unico. يجب أن تستخدم جميع النطاقات بروتوكول HTTPS.

الخطوة 2 — استدعاء init(options)

يُهيئ SDK ويحمّل الأصول مسبقاً، مما يوفر تجربة أكثر سلاسة للمستخدم النهائي. استدعِ هذه الوظيفة في أقرب وقت ممكن في تدفق عملك.

المعامل	مطلوب	الوصف
type	نعم	اضبط على 'IFRAME' لتدفقات by Unico
token	نعم	رمز العملية المُعاد من واجهة برمجة إنشاء العملية
env	لا	اضبط على 'uat' لبيئات الاختبار فقط

import { ByUnicoSDK } from "idpay-b2b-sdk";

ByUnicoSDK.init({
  type: 'IFRAME',
  token,
  // env: 'uat' // only for test environments
});

الخطوة 3 — استدعاء open(options)

يعرض iFrame المحمّل مسبقاً ويبدأ تدفق الرسائل بين صفحتك ورحلة Unico.

المعامل	مطلوب	الوصف
transactionId	نعم	معرِّف العملية المُعاد من واجهة برمجة إنشاء العملية
token	نعم	رمز العملية المُعاد من واجهة برمجة إنشاء العملية
onFinish	نعم	دالة رد النداء التي تُنفَّذ عند انتهاء الرحلة أو إغلاقها

تتلقى دالة رد النداء onFinish كائن عملية يحتوي على معرِّف المعاملة وعنوان URL لإعادة التوجيه ونوع الإتمام.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: (process) => {
    console.log('Process finished', process);
    // process.transaction.redirectUrl — use this to navigate the user
  },
});

// To close the SDK explicitly at any point:
ByUnicoSDK.close();

يوضح مخطط التسلسل أدناه كيفية استخدام SDK ونتيجة الواجهة البرمجية لتهيئة iFrame:

الأمان

اختيار حل iFrame مع رمز المصادقة بدلاً من CSP

بعد تحليل دقيق، يعتمد النهج المختار iframes مع رموز المصادقة بدلاً من تطبيق سياسة أمان المحتوى (CSP). جاء هذا القرار مدفوعاً بمتطلبات الأمان والمرونة اللازمة لتلبية احتياجات العملاء.

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

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

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

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

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

للتخفيف من هذه المخاطر وتلبية المرونة التي يتطلبها العملاء، يجمع الحل المختار بين iframes ورموز المصادقة، مما يوفر طبقة أمان إضافية دون الحاجة إلى قائمة نطاقات ثابتة.

آلية العمل:

• المصادقة الآمنة — يُحمَّل كل iFrame برمز مصادقة فريد لكل معاملة، مما يضمن أن المستخدمين المصرّح لهم فقط يمكنهم الوصول إلى المحتوى. يُتحقق من الرمز في الوقت الفعلي.
• عزل المحتوى — يعمل iFrame في سياق تصفح منفصل، مما يقلل من خطر التداخل بين مصادر مختلفة ويخفف من الهجمات المحتملة.
• المرونة للنطاقات الديناميكية — من خلال عدم الاعتماد على سياسة CSP ثابتة، يتكيف الحل مع نطاقات العملاء الديناميكية دون الحاجة إلى تحديثات مستمرة للسياسة.