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

Markdown

تصف هذه الصفحة كيفية عمل رحلات Unico ونماذج التكامل المتاحة لتضمينها في تطبيق.

الرحلة هي مجموعة الخطوات التي يمر بها المستخدم لإكمال عملية التحقق من الهوية. على سبيل المثال: التقاط صورة مستند وإجراء التقاط وجه (كشف الحيوية).

تدير Unico التجربة بالكامل. جهد التكامل ضئيل: يتم إنشاء الرحلة عبر CreateProcess، ويتم توجيه المستخدم إليها، ويتم استلام النتيجة في النهاية. كل شيء بينهما — الشاشات والتعليمات والتحققات — مبني ومُصان بالفعل من قبل Unico.

نموذجا التكامل

لكل عميل احتياجات مختلفة. تقدم Unico نموذجين لتوجيه المستخدم إلى الرحلة.

النموذج	الأفضل لـ
الوصول المباشر	تطبيقات الهاتف المحمول التي تستخدم WebView بالفعل، أو تدفقات الويب حيث يمكن أن تحدث الرحلة خارج الصفحة الرئيسية
Journeys SDK	تطبيقات الويب التي تحتاج إلى تجربة متكاملة وسلسة، مع إبقاء المستخدم في نفس البيئة

الوصول المباشر

يتم إعادة توجيه المستخدم إلى رابط مستضاف من Unico، حيث تتم الرحلة. عند الانتهاء، يتم إعادته إلى عنوان URL المحدد أثناء إنشاء العملية (معلمة callbackUri).

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

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

• إعادة توجيه قياسية. يتم إعادة توجيه المستخدم مباشرة إلى عنوان URL الخاص بالرحلة. عند الانتهاء، تعيد Unico توجيهه إلى callbackUri المحدد أثناء إنشاء العملية.
• علامة تبويب جديدة باستخدام window.open(). يتم فتح الرحلة في علامة تبويب متصفح جديدة، مع إبقاء المستخدم في سياق منفصل. في هذه الحالة، يُوصى بمراقبة تغيير عنوان URL إلى callbackUri وإغلاق علامة التبويب بمجرد اكتمال العملية. راجع وثائق MDN للحصول على تفاصيل حول الواجهة البرمجية.

في تطبيقات الهاتف المحمول، من الشائع استخدام WebView لفتح الرحلة مباشرة، دون الحاجة إلى إعادة توجيه إضافية. في هذه الحالة، يقبل callbackUri أيضًا deeplink، مما يسمح لإكمال الرحلة بتشغيل فتح شاشة محددة في التطبيق الأصلي. ما عليك سوى تكوين الـ deeplink كوجهة العودة ويتولى نظام التشغيل توجيه المستخدم إلى المكان الصحيح.

Journeys SDK

تتم الرحلة داخل التطبيق نفسه، دون إخراج المستخدم من سياقه. يتم تثبيت Journeys SDK في التطبيق واستخدامه لفتح الرحلة عند الحاجة.

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

توفر Unico مكتبة JavaScript متوافقة مع المتصفحات الحديثة، مما يسمح بدمج الرحلة في أي تطبيق تقريبًا ببضعة أسطر من التعليمات البرمجية.

التوافق

صُممت المكتبة لتناسب أي مشروع دون احتكاك، بغض النظر عن المكدس التقني المستخدم:

• أي تطبيق ويب. موزعة بتنسيق UMD، تعمل عند استيرادها عبر أدوات التجميع الحديثة (مثل webpack أو Vite). متوافقة مع أي إطار عمل (React، Angular، Vue) أو JavaScript خالص.
• المتصفحات الحديثة. تتضمن المكتبة بالفعل الـ polyfills اللازمة لميزات مثل Promises و async/await، مما يوسع التوافق إلى إصدارات المتصفحات الأقدم أيضًا.
• واجهات برمجة الويب القياسية. تعمل الرحلة على إمكانيات المتصفح الأصلية، دون اعتماد على إضافات أو مكتبات خارجية في المشروع.

كيف يعمل SDK داخليًا

عند فتح رحلة، يقوم SDK بإدراج iFrame في الصفحة ويتولى التحكم في التجربة المرئية بالكامل من تلك النقطة فصاعدًا. تعمل الشاشات والنصوص البرمجية والأصول لكل خطوة داخل هذا الـ iFrame، من لحظة بدء المستخدم حتى إكمال العملية.

هذا القرار المعماري مقصود: يضمن عزل iFrame أن رحلة Unico لا تتداخل مع أنماط التطبيق أو سلوكه. لا يتسرب أي نص برمجي إلى السياق الخارجي، ولا تتعارض أي قاعدة CSS مع أنماط التطبيق. النتيجة هي تجربة متسقة للمستخدم النهائي وتأثير أدنى على منتج العميل.

نظرًا لأن Unico مسؤولة عن إنشاء وإدارة iFrame، فإن تحسينات الرحلة — سواء في الأداء أو التجربة أو التحقق — يتم تسليمها تلقائيًا لجميع المستخدمين، دون الحاجة إلى تغييرات في التطبيق المتكامل. سيعمل التكامل دائمًا بأفضل التحسينات المتاحة، دون الحاجة إلى تتبع أو الاستجابة لكل تحديث للمنصة.

البدء

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

حزمة idpay-b2b-sdk مشتركة بين رحلات الدفع IDPay ورحلات التحقق من الهوية. لحالات استخدام الهوية، استورد فئة ByUnicoSDK كما هو موضح في الخطوات أدناه.

  npm install idpay-b2b-sdk

الطريقة الموصى بها لتثبيت Journeys SDK هي من خلال مدير حزم مثل npm أو yarn، من الحزمة المتاحة على npm registry. بالإضافة إلى تبسيط التثبيت وإدارة التبعيات، يوفر هذا النهج تحكمًا واضحًا في الإصدار المستخدم ويجعل التحديث سهلاً عند نشر إصدار جديد.

يتبع SDK الإصدار الدلالي (SemVer)، مما يعني أن تحديثات الإصلاح والتحديثات الثانوية لا تُدخل تغييرات جذرية. من الآمن تكوين المشروع لتلقي هذه التحديثات تلقائيًا. التغييرات التي قد تتطلب تحديثات التكامل محجوزة للإصدارات الرئيسية وتأتي دائمًا مع دليل ترحيل.

الحفاظ على تحديث SDK

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

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

الخطوة 2 — تكوين CSP و Permissions-Policy

إذا كانت صفحتك ترسل بالفعل رؤوس Content-Security-Policy أو Permissions-Policy، أضف التوجيهات التالية حتى يعمل iFrame والنصوص البرمجية والوصول إلى الكاميرا الخاصة بـ SDK بشكل صحيح.

Content-Security-Policy:

frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;

Permissions-Policy:

camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");

معلومة

إذا كانت صفحتك لا ترسل رؤوس CSP أو Permissions-Policy، يمكنك تخطي هذه الخطوة — المتصفح لا يطبق أي قيود بشكل افتراضي.

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

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

المعلمة	مطلوب	الوصف
token	نعم	رمز العملية الذي تم إرجاعه بواسطة واجهة Create Process API
env	لا	اضبط على 'uat' لبيئات الاختبار فقط

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

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

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

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

المعلمة	مطلوب	الوصف
transactionId	نعم	معرف العملية الذي تم إرجاعه بواسطة واجهة Create Process API
token	نعم	رمز العملية الذي تم إرجاعه بواسطة واجهة Create Process API
onFinish	نعم	دالة رد الاتصال التي تُنفذ عند انتهاء الرحلة أو إغلاقها
onWidgetVisibilityChange	لا	دالة رد الاتصال التي تُنفذ عند تغيير حالة ظهور الأداة

يحدث التفاعل التالي مع التطبيق عند انتهاء الرحلة، سواء أكملها المستخدم أو أغلقها. في تلك اللحظة، يستدعي SDK دالة onFinish، المُمرّرة كمعلمة في open. من هناك، يمكن للتطبيق استدعاء واجهة getProcess API للتحقق من النتيجة، أو انتظار إشعار Webhook إذا كان النهج غير المتزامن مفضلاً.

بالإضافة إلى الاستعلام عن النتيجة، يُوصى باستخدام onFinish للتعامل مع حالة الواجهة الأمامية للتطبيق:

• تجنب الحلقات. منع إعادة الإنشاء الفوري وغير الضروري للعمليات في حالة قيام المستخدم بتشغيل التدفق مرة أخرى مباشرة بعد انتهاء الرحلة.
• إدارة التدفق. ضمان توجيه المستخدم إلى الخطوة التالية من التطبيق، وتجنب شاشة طريق مسدود بعد إغلاق الرحلة.

تحذير

تشير دالة onFinish إلى أن المستخدم قد أكمل الرحلة، لكنها لا تضمن الموافقة. قد تكون العملية قد انتهت بفشل في إحدى قواعد التحقق من Unico. الاستعلام عبر getProcess أو تلقي إشعار Webhook ليس اختياريًا: هذه هي المصادر الوحيدة للنتيجة الفعلية، ويجب أن يستند سلوك التطبيق إليها. يجب عدم استخدام onFinish بمعزل عن غيرها لتحديد ما إذا تمت الموافقة على المستخدم.

تتلقى دالة onFinish كائنًا يصف كيفية انتهاء الرحلة:

الحقل	النوع	الوصف
type	string	كيف انتهت الرحلة: 'FINISH' (مكتملة) أو 'CLOSE' (أغلق المستخدم قبل الإنهاء)
transaction	object | undefined	موجود عندما يكون type هو 'FINISH'؛ undefined عندما يكون type هو 'CLOSE'
transaction.id	string	معرف العملية (نفس transactionId المُمرّر)
transaction.redirectUrl	string	عنوان URL لإعادة توجيه المستخدم بعد الرحلة

التعامل مع دالة onWidgetVisibilityChange اختياري وقد لا يكون ذا صلة بحالة استخدامك. يتم استدعاؤها كلما تغيرت حالة ظهور الأداة، وهي مفيدة فقط في سيناريو محدد: بعض الرحلات تعرض خلفية شفافة، مما يُبقي صفحة التطبيق مرئية خلف التجربة. التطبيقات التي تعرض نافذة منبثقة مخصصة أثناء تدفق التحقق (على سبيل المثال، كجزء من تنسيق عبر عدة مزودي KYC) قد ينتهي بها الأمر بعرض تلك النافذة المنبثقة خلف أداة Unico، مما يُضعف التجربة المرئية. في هذه الحالة، تتيح الدالة للتطبيق إخفاء أي عناصر مرئية إضافية أثناء نشاط رحلة Unico، واستعادتها بمجرد انتهائها. إذا لم يكن لتطبيقك واجهة مستخدم يمكن أن تتداخل مع الأداة، يمكنك حذفها بأمان.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: ({ transaction, type }) => {
    if (type === 'FINISH') {
      // Journey completed (transaction = { id, redirectUrl }) — continue your flow here.
    }
    // type === 'CLOSE' → user closed before finishing;
  },
  // Optional: only needed if your app shows UI that could overlap the widget.
  onWidgetVisibilityChange: (visible) => {
    // suppress or restore your modal based on widget visibility
  },
});

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

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

تطبيقات نموذجية

اللغة / إطار العمل	الوصف	المستودع
Angular	إثبات مفهوم في Angular يُنفذ Journeys SDK	GitHub — unico-cbu-poc-angular
JS Vanilla	إثبات مفهوم في JS Vanilla يُنفذ Journeys SDK	GitHub — unico-cbu-poc-js
React	إثبات مفهوم في React يُنفذ Journeys SDK	GitHub — unico-cbu-poc-react
Vue JS	إثبات مفهوم في Vue JS يُنفذ Journeys SDK	GitHub — unico-cbu-poc-vuejs

الأمان

الأمان في هذا النموذج مبني على طبقات، بدءًا من بروتوكول الاتصال بين SDK والتطبيق الذي يعمل داخل iFrame.

عند تحميل الرحلة، يقوم كلا الطرفين بإجراء مصافحة لإنشاء الاتصال. في هذه العملية، يتحقق تطبيق Unico من أصل رسالة حقن البيانات المستلمة عبر postMessage مقابل قائمة مغلقة من النطاقات المعتمدة، مقسمة حسب البيئة (UAT و PROD). يتم تجاهل الرسائل من أصول غير معتمدة فورًا، مما يمنع تضمين الرحلة في صفحات غير مصرح بها ويزيل سطح الهجوم لثغرات مثل clickjacking.

بالإضافة إلى التحقق من الأصل، لا يستمر التدفق إلا مع رمز معاملة صالح: JWT للاستخدام الواحد، صادر وموقّع من خلفية Unico. هذا يضمن أنه حتى الأصل المعتمد لا يمكنه العمل برمز منتهي الصلاحية أو مُعاد استخدامه أو مزيف.

بعد المصافحة، يتم حقن الرمز في iFrame ولا تتدفق أي معلومات حساسة بين الطرفين. جميع الاتصالات المتبقية تخدم فقط التحكم في الواجهة — الفتح والإغلاق وانتقالات الشاشات — مما يمنع اعتراض بيانات العملية أو تسربها أثناء الرحلة.

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

CSP و Permissions-Policy

إذا كانت صفحتك ترسل رؤوس Content-Security-Policy أو Permissions-Policy، تأكد من وجود التوجيهات التالية حتى يعمل iFrame والنصوص البرمجية والوصول إلى الكاميرا الخاصة بـ SDK بشكل صحيح.

Content-Security-Policy:

frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;

Permissions-Policy:

camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io");

إذا كانت صفحتك لا ترسل هذه الرؤوس، فإن المتصفح لا يطبق أي قيود بشكل افتراضي ولا حاجة لأي تكوين.

استكشاف أخطاء SDK وإصلاحها

يغطي هذا القسم المشكلات الأكثر شيوعًا التي تواجهها أثناء التكامل والطرق الموصى بها للتحقيق فيها.

سلوك غير متوقع أو تدفق معطل

تحقق مما إذا كان أي نص برمجي في التطبيق يتلاعب مباشرة بـ iFrame في DOM. ينشئ SDK ويدير iFrame في body الصفحة، وأي تعديل خارجي — سواء في النطاق أو الموضع أو السمات — يمكن أن يتداخل مع دورة حياة الرحلة ويسبب سلوكًا غير متوقع.

تجربة مرئية مختلفة عن المتوقع

تحقق مما إذا كانت أي ورقة أنماط عامة في التطبيق تتجاوز الخصائص داخل iFrame. ينشئ SDK الـ iFrame وجميع عناصره الداخلية بمعرفات ديناميكية وفئات مسبوقة بـ unico، مما يقلل بشكل كبير من خطر التعارض عبر محددات المعرف أو الفئة. ومع ذلك، فإن قواعد CSS الواسعة — مثل محددات الوسوم — يمكن أن تصل إلى عناصر داخل iFrame وتغير التجربة المرئية المقدمة للمستخدم.

ملفات مكتبة SDK معدلة مباشرة

تحقق مما إذا كان أي ملف مكتبة قد تم تعديله خارج مدير الحزم. يجب إدارة المكتبة حصريًا عبر npm أو yarn، دون تعديلات مباشرة على الملفات المثبتة. يمكن أن تنتج التعديلات اليدوية سلوكًا شاذًا يصعب إعادة إنتاجه وستمنع دعم Unico من القدرة على المساعدة.

لا تبقِ DevTools مفتوحة أثناء اختبارات الالتقاط

يستخدم تطبيق Unico حزمة Capture SDK (unico-webframe) لالتقاط الوجه، والتي تكتشف DevTools المفتوحة كإشارة احتيال محتملة وتحظر الإرسال. أغلق DevTools قبل تشغيل اختبارات الالتقاط الشاملة.

عمليات التكامل غير المدعومة

النماذج الموصوفة في هذه الوثائق — الوصول المباشر و Journeys SDK — هي نهج التكامل الوحيدة المدعومة رسميًا من Unico. قد تتسبب عمليات التكامل التي تنحرف عن هذه المعايير في سلوك غير متوقع وفشل في تدفقات الأمان وانقطاعات في الرحلة، ولن يتم تغطيتها من قبل دعم Unico.

أمثلة على النُهج غير المدعومة:

• تضمين SDK داخل WebView في تطبيقات الهاتف المحمول. في هذه الحالات، النهج الصحيح هو استخدام نموذج الوصول المباشر، بفتح رابط الرحلة مباشرة في WebView دون إشراك Journeys SDK.
• تحميل iFrame مباشرة عبر وسم HTML <iframe>، دون المرور عبر Journeys SDK. الـ iFrame هو تفصيل تنفيذ داخلي لـ SDK ويجب عدم إنشائه يدويًا. النهج الصحيح هو استخدام Journeys SDK، الذي يدير دورة حياة iFrame بشكل آمن وضمن المعايير المتوقعة.

إذا كان هناك أي شك حول ما إذا كان النهج ضمن المعيار المدعوم، استشر الوثائق أو اتصل بالدعم قبل المضي في التنفيذ.