--- title: تكامل تطبيق الويب description: كيفية دمج عقد Web & SDK على جانب العميل — تدفقات إعادة التوجيه وإعداد iFrame SDK. canonical: https://developer.unico.io/ar/dual-api/developers/sdks-and-tools/web/web-integration/ locale: ar generated_by: markdown-export --- تصف هذه الصفحة كيفية عمل رحلات Unico ونماذج التكامل المتاحة لدمجها في أحد التطبيقات. **الرحلة** هي مجموعة الخطوات التي يمر بها المستخدم لإتمام التحقق من الهوية. على سبيل المثال: التقاط صورة للمستند وإجراء التقاط للوجه (لايفنس). تتولى Unico إدارة التجربة بأكملها. جهد التكامل ضئيل: تُنشأ الرحلة عبر **CreateProcess**، ويُوجَّه المستخدم إليها، وتُستلَم النتيجة في النهاية. كل ما يحدث في الأثناء (الشاشات والتعليمات وعمليات التحقق) جاهز بالفعل وتتولى Unico صيانته. :::tip[اختيار نهج التكامل المناسب] - **Web SDK** (حزمة `unico-webframe`): استخدمها عندما يتحكم الـ back-end لديك بالفعل في تدفق التحقق من الهوية ويحتاج فقط إلى مكوّن الالتقاط من جانب العميل. تُعيد `base64` + رمز JWT مشفّرًا مباشرةً إلى الـ callback الخاص بك؛ وأنت من يدير استدعاءات الـ API. - **Web App Integration** (حزمة `idpay-b2b-sdk`): استخدمها عندما تريد أن تتولى Unico تنسيق الرحلة بأكملها (تدفقات متعددة الخطوات، التقاط المستند + لايفنس). حزمة `idpay-b2b-sdk` تشغّل نموذج **Journeys SDK** (iFrame) المضمَّن؛ أما نموذج **الوصول المباشر** (إعادة التوجيه) فلا يحتاج إلى أي مكتبة. ::: ## نموذجا التكامل لكل عميل احتياجات مختلفة. تقدّم Unico **نموذجين** لتوجيه المستخدم إلى الرحلة. | النموذج | الأنسب لـ | | ------------------- | ------------------------------------------------------------------------------------------------------- | | **الوصول المباشر** | تطبيقات الجوال التي تستخدم بالفعل WebView، أو تدفقات الويب التي يمكن أن تتم فيها الرحلة خارج الصفحة الرئيسية | | **Journeys SDK** | تطبيقات الويب التي تحتاج إلى تجربة متكاملة وسلسة، مع إبقاء المستخدم داخل البيئة نفسها | ### الوصول المباشر يُعاد توجيه المستخدم إلى **رابط مُستضاف من Unico**، حيث تتم الرحلة. وعند الاكتمال، يُعاد إلى عنوان URL المحدَّد أثناء إنشاء العملية (المعامل `callbackUri`). هذا هو أبسط نهج يمكن اعتماده: فهو لا يتطلب تثبيت أي مكتبة، ويعمل جيدًا عندما لا تحتاج الرحلة إلى أن تتم داخل صفحة التطبيق نفسها. في المقابل، فإن نقل المستخدم خارج بيئة العميل يميل إلى إحداث مزيد من الاحتكاك، ومن ثَمّ معدل تخلٍّ أعلى. بعد إنشاء عملية، تتضمن استجابة الـ API عنوان URL للرحلة المستضافة من Unico. هناك طريقتان شائعتان لتوجيه المستخدم إليها: - **إعادة التوجيه القياسية.** يُعاد توجيه المستخدم مباشرةً إلى عنوان URL للرحلة. وعند الاكتمال، تعيد Unico توجيهه إلى `callbackUri` المحدَّد أثناء إنشاء العملية. - **علامة تبويب جديدة باستخدام `window.open()`.** تُفتح الرحلة في علامة تبويب جديدة في المتصفح، مما يُبقي المستخدم في سياق منفصل. في هذه الحالة، يُوصى بمراقبة تغيُّر عنوان URL إلى `callbackUri` وإغلاق علامة التبويب بمجرد اكتمال العملية. للاطلاع على تفاصيل حول الـ API، راجع [توثيق MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/open). ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant Hosted as Unico hosted frontend application Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Frontend->>Hosted: redirect user to process url Note over Hosted: User journey Hosted->>Frontend: redirect user to callback url critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` في تطبيقات الجوال، من الشائع استخدام **WebView** لفتح الرحلة مباشرةً دون الحاجة إلى إعادة توجيه إضافية. في هذه الحالة، يقبل `callbackUri` أيضًا **deeplink**، مما يتيح أن يؤدي اكتمال الرحلة إلى فتح شاشة محددة في التطبيق الأصلي. ما عليك سوى ضبط الـ deeplink كوجهة عودة، ويتولى نظام التشغيل توجيه المستخدم إلى المكان الصحيح. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant App as Customer mobile application participant Hosted as Unico hosted frontend application App->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>App: return Unico process info App->>Hosted: open the process url in a webview Note over Hosted: User journey Hosted->>App: redirect user to the deeplink (callback url) critical Get process result App->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` ### Journeys SDK تتم الرحلة **داخل التطبيق نفسه**، دون إخراج المستخدم من سياقه. يُثبَّت **Journeys SDK** في التطبيق ويُستخدم لفتح الرحلة عند الحاجة. هذا هو المسار الموصى به للحصول على تجربة أكثر تكاملًا وسلاسة، مع إبقاء المستخدم في البيئة نفسها طوال الوقت، مما يميل إلى تقليل الاحتكاك ومعدل التخلي على امتداد التدفق. تقدّم Unico مكتبة JavaScript متوافقة مع المتصفحات الحديثة، تتيح دمج الرحلة في أي تطبيق تقريبًا بأسطر قليلة من التعليمات البرمجية. #### التوافق صُمِّمت المكتبة لتندمج في أي مشروع دون احتكاك، بغضّ النظر عن الـ stack المُستخدَم: - **أي تطبيق ويب.** تُوزَّع بصيغة 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` كما هو موضح في الخطوات أدناه. ```bash npm install idpay-b2b-sdk ``` الطريقة الموصى بها لتثبيت Journeys SDK هي عبر مدير اعتماديات مثل **npm** أو **yarn**، من الحزمة المتاحة على **npm registry**. وإلى جانب تبسيط التثبيت وإدارة الاعتماديات، يوفّر هذا النهج تحكمًا واضحًا في الإصدار المُستخدَم ويُسهّل التحديث في كل مرة يُنشر فيها إصدار جديد. يتبع الـ SDK **الإصدار الدلالي (SemVer)**، ما يعني أن تحديثات patch وminor لا تُدخِل تغييرات كاسرة للتوافق. ومن الآمن تهيئة المشروع لتلقّي هذه التحديثات تلقائيًا. أما التغييرات التي قد تتطلب تعديلات في التكامل فهي محصورة في إصدارات major وتأتي دائمًا مصحوبة بدليل ترحيل. :::tip[حافظ على تحديث الـ SDK] البقاء على أحدث إصدار مهم بشكل خاص لسببين. الأول هو **الأمان**: تُنشر تصحيحات الأمان كلما اكتُشفت ثغرات أو سنحت فرص لتعزيز بروتوكول الاتصال. وتشغيل إصدار قديم يعني التخلي عن هذه الإصلاحات وتعريض التدفق لمخاطر غير ضرورية. والثاني هو **الاستقرار**: تُوزَّع إصلاحات الأخطاء بالطريقة نفسها، وقد تُظهر الإصدارات القديمة سلوكيات سبق حلّها في الإصدارات الأحدث. ::: قبل البدء، سجّل نطاقاتك لدى فريق دعم Unico. يجب أن تستخدم جميع النطاقات HTTPS. ****الخطوة 2**: استدعِ `init(options)`** يُهيّئ الـ SDK ويُحمّل مسبقًا النصوص البرمجية اللازمة لعمل الرحلة بشكل صحيح، مما يوفّر تجربة أكثر سلاسة للمستخدم النهائي. استدعِه في أبكر وقت ممكن في التدفق. | المعامل | مطلوب | الوصف | | ------- | ----- | ---------------------------------------------------- | | `token` | نعم | رمز العملية المُعاد من واجهة Create Process البرمجية | | `env` | لا | اضبطه على `'uat'` لبيئات الاختبار فقط | ```javascript import { ByUnicoSDK } from 'idpay-b2b-sdk'; ByUnicoSDK.init({ token, // env: 'uat' // لبيئات الاختبار فقط }); ``` ****الخطوة 3**: استدعِ `open(options)`** يعرض الـ iFrame ويبدأ الرحلة للمستخدم. من هذه النقطة فصاعدًا، يحدث كل شيء تلقائيًا داخل الـ iFrame، دون الحاجة إلى إدارة أي خطوة وسيطة. | المعامل | مطلوب | الوصف | | -------------------------- | ----- | ------------------------------------------------------ | | `transactionId` | نعم | معرّف العملية المُعاد من واجهة Create Process البرمجية | | `token` | نعم | رمز العملية المُعاد من واجهة Create Process البرمجية | | `onFinish` | نعم | دالة رد نداء تُنفَّذ عند انتهاء الرحلة أو إغلاقها | | `onWidgetVisibilityChange` | لا | دالة رد نداء تُنفَّذ عند تغيُّر حالة ظهور الأداة | يحدث التفاعل التالي مع التطبيق عند انتهاء الرحلة، سواء أكملها المستخدم أم أغلقها. في تلك اللحظة، يستدعي الـ SDK دالة رد النداء **`onFinish`** المُمرَّرة كمعامل في `open`. ومن هناك، يمكن للتطبيق استدعاء واجهة **`getProcess`** البرمجية للتحقق من النتيجة، أو انتظار إشعار عبر **Webhook** إذا كان النهج غير المتزامن مفضّلًا. بالإضافة إلى الاستعلام عن النتيجة، يُوصى باستخدام `onFinish` لمعالجة حالة الواجهة الأمامية للتطبيق: - **تجنّب الحلقات.** امنع إعادة إنشاء العمليات فورًا ودون داعٍ إذا أعاد المستخدم تشغيل التدفق مباشرةً بعد انتهاء الرحلة. - **إدارة التدفق.** تأكّد من توجيه المستخدم إلى الخطوة التالية في التطبيق، لتفادي بقائه عالقًا في شاشة بلا مخرج بعد إغلاق الرحلة. :::warning تشير دالة رد النداء `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 نشطة، واستعادتها بمجرد انتهائها. وإذا لم يكن لدى تطبيقك أي واجهة مستخدم قد تتداخل مع الأداة، فيمكنك حذفها بأمان. ```javascript ByUnicoSDK.open({ transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf', token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', onFinish: ({ transaction, type }) => { if (type === 'FINISH') { // اكتملت الرحلة (transaction = { id, redirectUrl }): تابِع تدفقك هنا. } // type === 'CLOSE' → أغلق المستخدم قبل الانتهاء; }, // اختياري: مطلوب فقط إذا كان تطبيقك يعرض واجهة قد تتداخل مع الأداة. onWidgetVisibilityChange: (visible) => { // أخفِ نافذتك المنبثقة أو استعِدها بناءً على ظهور الأداة }, }); // لإغلاق الـ SDK صراحةً في أي وقت: ByUnicoSDK.close(); ``` يوضّح مخطط التسلسل أدناه كيفية استخدام الـ SDK ونتيجة الـ API لتهيئة الـ iFrame: ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant SDK as ByUnicoSDK Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Note over Frontend: Initialize the Unico journey as soon as it is determined that the KYC flow is required critical Unico journey initialization Frontend->>SDK: byUnicoSDK.init SDK-->>Frontend: validates customer domain and initialize end critical Unico journey exhibition Frontend->>SDK: byUnicoSDK.open SDK-->>Frontend: show byUnico experience end Note over SDK: User journey critical Unico journey completion SDK-->>Frontend: call onFinish end critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` #### تطبيقات نموذجية | اللغة / الإطار | الوصف | المستودع | | --------------------- | ------------ | ---------- | | Angular | إثبات مفهوم (PoC) بـ Angular يُطبّق Journeys SDK | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | إثبات مفهوم (PoC) بـ JS Vanilla يُطبّق Journeys SDK | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | إثبات مفهوم (PoC) بـ React يُطبّق Journeys SDK | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | إثبات مفهوم (PoC) بـ Vue JS يُطبّق Journeys SDK | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/unico-cbu-poc-vuejs) | #### الأمان :::note[نطاق هذا القسم] ينطبق مبرّر الأمان هذا تحديدًا على **Web App Integration** (`idpay-b2b-sdk`). يستخدم **Web SDK** (`unico-webframe`) نموذجًا مختلفًا: فهو يعمل بالكامل في سياق الصفحة و[يتطلب CSP فعلًا](/dual-api/developers/sdks-and-tools/web/web-sdk/installation). وهما منتجان مختلفان بمعماريتَي أمان مختلفتين. ::: الأمان في هذا النموذج مبني على طبقات، بدءًا من بروتوكول الاتصال بين الـ SDK والتطبيق الذي يعمل داخل الـ iFrame. عند تحميل الرحلة، ينفّذ الطرفان **مصافحة (handshake)** لإنشاء الاتصال. وفي هذه العملية، يتحقق تطبيق Unico من مصدر رسالة حقن البيانات المستلَمة عبر `postMessage` مقابل قائمة مغلقة من النطاقات المصرّح بها، مقسّمة حسب البيئة (UAT وPROD). وتُرفض الرسائل الواردة من مصادر غير معتمدة على الفور، مما يمنع تضمين الرحلة في صفحات غير مصرّح بها ويزيل سطح الهجوم لثغرات مثل **clickjacking**. بالإضافة إلى التحقق من المصدر، لا يتقدّم التدفق إلا مع رمز معاملة صالح: رمز JWT للاستخدام مرة واحدة، صادر وموقّع من الواجهة الخلفية لـ Unico. وهذا يضمن ألا يتمكن حتى مصدر مصرّح به من العمل برمز منتهي الصلاحية أو مُعاد استخدامه أو مزوَّر. بعد المصافحة، يُحقَن الرمز في الـ iFrame ولا تتدفق بعد ذلك أي معلومات حساسة بين الطرفين. ويخدم كل الاتصال المتبقي التحكمَ في الواجهة فقط (الفتح والإغلاق وانتقالات الشاشات)، مما يمنع اعتراض بيانات العملية أو تسريبها أثناء الرحلة. كما يحمي عزل الـ iFrame سلامة نصوص Unico البرمجية في وقت التشغيل. وبما أن الكود يعمل في سياق منفصل عن الصفحة، فلا يمكن للنصوص البرمجية الخارجية الوصول إليه أو تعديله، مما يضمن تنفيذ الرحلة تمامًا كما بُنيت، دون أي تدخّل. بحكم التصميم، لا نعتمد CSP في نموذج التكامل هذا. فالنطاقات المصرّح بها جزء من تهيئة الأمان لكل عميل، وقد يؤدي كشفها علنًا في الترويسات إلى تسهيل رسم خريطة البنية التحتية على الجهات الخبيثة. وبما أن تحديد هوية العميل لا يحدث إلا عند `init`، فلا يمكن حقن هذه النطاقات ديناميكيًا في الترويسات قبل تلك اللحظة، مما يجعل CSP غير عملي دون التخلي عن هذه الخصوصية. وتُوفَّر جميع ضمانات الأمان من خلال بروتوكول المصافحة الموضّح أعلاه. #### استكشاف أخطاء الـ SDK وإصلاحها يتناول هذا القسم أكثر المشكلات شيوعًا التي تُصادَف أثناء التكامل والطرق الموصى بها للتحقيق فيها. ##### سلوك غير متوقع أو تدفق متوقف تحقق مما إذا كان أي نص برمجي في التطبيق يتلاعب مباشرةً بالـ iFrame في الـ DOM. ينشئ الـ SDK الـ iFrame ويديره داخل `body` الصفحة، وأي تعديل خارجي (سواء في النطاق أو الموضع أو السمات) قد يتداخل مع دورة حياة الرحلة ويسبّب سلوكًا غير متوقع. ##### تجربة مرئية مختلفة عن المتوقع تحقق مما إذا كانت أي ورقة أنماط عامة في التطبيق تتجاوز خصائص داخل الـ iFrame. ينشئ الـ SDK الـ iFrame وجميع عناصره الداخلية بمعرّفات ديناميكية وفئات مسبوقة بـ `unico`، مما يقلّل بشكل كبير من خطر التعارض عبر محدِّدات المعرّف أو الفئة. ومع ذلك، فإن قواعد CSS ذات النطاق الواسع (مثل محدِّدات الوسوم) قد تصل إلى عناصر داخل الـ iFrame وتغيّر التجربة المرئية المقدَّمة للمستخدم. ##### تعديل ملفات مكتبة الـ SDK مباشرةً تحقق مما إذا كان أي ملف من ملفات المكتبة قد عُدِّل خارج مدير الاعتماديات. يجب إدارة المكتبة حصريًا عبر **npm** أو **yarn**، دون إجراء تعديلات مباشرة على الملفات المثبَّتة. فقد تؤدي التعديلات اليدوية إلى سلوك شاذ يصعب إعادة إنتاجه وتجعل تقديم الدعم من Unico متعذّرًا. #### لا تُبقِ DevTools مفتوحة أثناء اختبارات الالتقاط يستخدم تطبيق Unico الـ Capture SDK (unico-webframe) لالتقاط الوجه، وهو يكتشف أدوات DevTools المفتوحة كإشارة احتيال محتملة ويحظر الإرسال. أغلِق DevTools قبل تشغيل اختبارات الالتقاط الشاملة (end-to-end). :::warning[عمليات تكامل غير مدعومة] النماذج الموضّحة في هذه الوثائق (الوصول المباشر وJourneys SDK) هي طرق التكامل الوحيدة المدعومة رسميًا من Unico. وقد تتسبب عمليات التكامل التي تحيد عن هذه المعايير في سلوك غير متوقع، وإخفاقات في تدفق الأمان، وانقطاعات في الرحلة، ولن تكون مشمولة بدعم Unico. بعض الأمثلة على الأنهج غير المدعومة: - **تضمين الـ SDK داخل WebView** في تطبيقات الجوال. في هذه الحالات، النهج الصحيح هو استخدام نموذج **الوصول المباشر**، بفتح رابط الرحلة مباشرةً في الـ WebView دون إشراك Journeys SDK. - **تحميل الـ iFrame مباشرةً عبر وسم HTML `