--- title: تكامل تطبيق الويب description: كيفية دمج عقد Web & SDK على جانب العميل — تدفقات إعادة التوجيه وإعداد iFrame SDK. canonical: https://developer.unico.io/ar/human-token/integrations/web/web-integration/ locale: ar generated_by: markdown-export --- تصف هذه الصفحة كيفية عمل رحلات Unico ونماذج التكامل المتاحة لتضمينها في تطبيق. **الرحلة** هي مجموعة الخطوات التي يمر بها المستخدم لإكمال عملية التحقق من الهوية. على سبيل المثال: التقاط صورة مستند وإجراء التقاط وجه (كشف الحيوية). تدير Unico التجربة بالكامل. جهد التكامل ضئيل: يتم إنشاء الرحلة عبر **CreateProcess**، ويتم توجيه المستخدم إليها، ويتم استلام النتيجة في النهاية. كل شيء بينهما — الشاشات والتعليمات والتحققات — مبني ومُصان بالفعل من قبل Unico. ## نموذجا التكامل لكل عميل احتياجات مختلفة. تقدم Unico **نموذجين** لتوجيه المستخدم إلى الرحلة. | النموذج | الأفضل لـ | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | **الوصول المباشر** | تطبيقات الهاتف المحمول التي تستخدم WebView بالفعل، أو تدفقات الويب حيث يمكن أن تحدث الرحلة خارج الصفحة الرئيسية | | **Journeys SDK** | تطبيقات الويب التي تحتاج إلى تجربة متكاملة وسلسة، مع إبقاء المستخدم في نفس البيئة | ### الوصول المباشر يتم **إعادة توجيه المستخدم إلى رابط مستضاف من Unico**، حيث تتم الرحلة. عند الانتهاء، يتم إعادته إلى عنوان URL المحدد أثناء إنشاء العملية (معلمة `callbackUri`). هذا هو أبسط نهج للتبني: لا يتطلب تثبيت أي مكتبة ويعمل جيدًا عندما لا تحتاج الرحلة إلى الحدوث داخل صفحة التطبيق نفسها. من ناحية أخرى، فإن أخذ المستخدم خارج بيئة العميل يميل إلى إدخال مزيد من الاحتكاك، وبالتالي معدل تسرب أعلى. بعد إنشاء عملية، يتضمن استجابة API عنوان URL لرحلة Unico المستضافة. هناك طريقتان شائعتان لتوجيه المستخدم إليها: - **إعادة توجيه قياسية.** يتم إعادة توجيه المستخدم مباشرة إلى عنوان URL الخاص بالرحلة. عند الانتهاء، تعيد Unico توجيهه إلى `callbackUri` المحدد أثناء إنشاء العملية. - **علامة تبويب جديدة باستخدام `window.open()`.** يتم فتح الرحلة في علامة تبويب متصفح جديدة، مع إبقاء المستخدم في سياق منفصل. في هذه الحالة، يُوصى بمراقبة تغيير عنوان URL إلى `callbackUri` وإغلاق علامة التبويب بمجرد اكتمال العملية. راجع [وثائق 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 متوافقة مع المتصفحات الحديثة، مما يسمح بدمج الرحلة في أي تطبيق تقريبًا ببضعة أسطر من التعليمات البرمجية. #### التوافق صُممت المكتبة لتناسب أي مشروع دون احتكاك، بغض النظر عن المكدس التقني المستخدم: - **أي تطبيق ويب.** موزعة بتنسيق 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)**، مما يعني أن تحديثات الإصلاح والتحديثات الثانوية لا تُدخل تغييرات جذرية. من الآمن تكوين المشروع لتلقي هذه التحديثات تلقائيًا. التغييرات التي قد تتطلب تحديثات التكامل محجوزة للإصدارات الرئيسية وتأتي دائمًا مع دليل ترحيل. :::tip[الحفاظ على تحديث 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"); ``` :::info إذا كانت صفحتك لا ترسل رؤوس CSP أو Permissions-Policy، يمكنك تخطي هذه الخطوة — المتصفح لا يطبق أي قيود بشكل افتراضي. ::: ****الخطوة 3** — استدعاء `init(options)`** يقوم بتهيئة SDK وتحميل النصوص البرمجية اللازمة مسبقًا لعمل الرحلة بشكل صحيح، مما يخلق تجربة أكثر سلاسة للمستخدم النهائي. استدعِ هذا في أقرب وقت ممكن في التدفق. | المعلمة | مطلوب | الوصف | | --------- | -------- | ------------------------------------------------ | | `token` | نعم | رمز العملية الذي تم إرجاعه بواسطة واجهة Create Process API | | `env` | لا | اضبط على `'uat'` لبيئات الاختبار فقط | ```javascript 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` للتعامل مع حالة الواجهة الأمامية للتطبيق: - **تجنب الحلقات.** منع إعادة الإنشاء الفوري وغير الضروري للعمليات في حالة قيام المستخدم بتشغيل التدفق مرة أخرى مباشرة بعد انتهاء الرحلة. - **إدارة التدفق.** ضمان توجيه المستخدم إلى الخطوة التالية من التطبيق، وتجنب شاشة طريق مسدود بعد إغلاق الرحلة. :::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') { // 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: ```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 | إثبات مفهوم في Angular يُنفذ Journeys SDK | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | إثبات مفهوم في JS Vanilla يُنفذ Journeys SDK | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | إثبات مفهوم في React يُنفذ Journeys SDK | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | إثبات مفهوم في Vue JS يُنفذ Journeys SDK | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/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 قبل تشغيل اختبارات الالتقاط الشاملة. :::warning[عمليات التكامل غير المدعومة] النماذج الموصوفة في هذه الوثائق — الوصول المباشر و Journeys SDK — هي نهج التكامل الوحيدة المدعومة رسميًا من Unico. قد تتسبب عمليات التكامل التي تنحرف عن هذه المعايير في سلوك غير متوقع وفشل في تدفقات الأمان وانقطاعات في الرحلة، ولن يتم تغطيتها من قبل دعم Unico. أمثلة على النُهج غير المدعومة: - **تضمين SDK داخل WebView** في تطبيقات الهاتف المحمول. في هذه الحالات، النهج الصحيح هو استخدام نموذج **الوصول المباشر**، بفتح رابط الرحلة مباشرة في WebView دون إشراك Journeys SDK. - **تحميل iFrame مباشرة عبر وسم HTML `