الالتقاط عبر الويب

خذ الشخص خلال عملية الالتقاط في المتصفح، باستخدام الرمز (token) والرابط اللذين يعيدهما Human Plugin.

Markdown

تنشئ الواجهة الخلفية لديك العملية في Human Plugin باستخدام تدفق Journey. يتضمن الرد 201 ثلاث قيم تحتاجها الواجهة الأمامية:

الحقل	الاستخدام
id	معرّف عملية Human Plugin. يأخذه SDK باسم transactionId، وتقرأ به الواجهة الخلفية لديك النتيجة
token	يبدأ عملية الالتقاط في Journeys SDK
link	صفحة الالتقاط المستضافة

يُعاد token وlink فقط عند الإنشاء. مرّرهما إلى الواجهة الأمامية في الطلب نفسه، أو خزّنهما بنفسك. راجع Human Token Journey.

المتطلبات

تعمل عملية الالتقاط في المتصفح وتحتاج إلى الوصول إلى الكاميرا.

نظام التشغيل	Chrome	Firefox	Safari	Samsung Internet	Opera	Edge
Windows	✅	✅	N/A	N/A	❌	❌
macOS	✅	✅	✅	N/A	❌	❌
Android	✅	❌	N/A	✅	❌	❌
iOS	✅	✅	✅	N/A	❌	❌

• يجب تقديم الصفحات عبر HTTPS. لا تعمل الكاميرا إلا في سياق آمن.
• يتطلب التصفح داخل التطبيقات Android 8 (API 26) أو iOS 13 أو أحدث.
• المتصفحات داخل تطبيقات الشبكات الاجتماعية غير مدعومة.

اختر نموذجًا

النموذج	الأنسب لـ
الرابط المستضاف	أبسط إعداد. بدون مكتبة: ينتقل الشخص إلى link ثم يعود إلى callbackUri الخاص بك
Journeys SDK	تُفتح عملية الالتقاط داخل صفحتك، فلا يغادرها الشخص

الرابط المستضاف

أرسل callbackUri في طلب الإنشاء. هي الصفحة التي يعود إليها الشخص عند انتهاء عملية الالتقاط.

{
  "flow": "humantoken",
  "clientId": "client-a",
  "correlationId": "order-1001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
  "callbackUri": "https://app.example.com/capture/done"
}

ثم وجّه الشخص إلى link بإحدى طريقتين:

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

عندما يعود الشخص، أخبر الواجهة الخلفية لديك، لتستدعي GET /v1/processes/{id}.

Journeys SDK

يفتح SDK عملية الالتقاط في iFrame داخل صفحتك. ويعمل مع أي إطار عمل (React وAngular وVue) أو مع JavaScript العادي.

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

1. التثبيت

npm install unico-journey-sdk

يتبع SDK الإصدار الدلالي (semantic versioning)، لذا فإن التحديثات الثانوية وتحديثات الإصلاح آمنة. أبقِه محدثًا: تصدر الإصلاحات الأمنية وإصلاحات الأخطاء في إصدارات جديدة.

2. السماح بـ SDK في الترويسات

تخطَّ هذه الخطوة إذا كانت صفحتك لا ترسل ترويسة Content-Security-Policy ولا Permissions-Policy. وإلا، أضف:

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")

3. التهيئة

استدعِ init بمجرد أن تعرف أن عملية الالتقاط مطلوبة. فهو يحمّل عملية الالتقاط مسبقًا.

import { ByUnicoSDK } from 'unico-journey-sdk';

ByUnicoSDK.init({ token });

4. فتح عملية الالتقاط

المعامل	مطلوب	القيمة
transactionId	نعم	قيمة id الخاصة بـ Human Plugin
token	نعم	قيمة token من عملية الإنشاء
onFinish	نعم	تُستدعى عند انتهاء عملية الالتقاط أو عندما يغلقها الشخص
onWidgetVisibilityChange	لا	تُستدعى عند إظهار عملية الالتقاط أو إخفائها

ByUnicoSDK.open({
  transactionId: id, // معرّف Human Plugin
  token,
  onFinish: ({ type }) => {
    if (type === 'FINISH') {
      // انتهت عملية الالتقاط. اطلب من الواجهة الخلفية لديك قراءة النتيجة.
    }
    // type === 'CLOSE': أغلقها الشخص قبل النهاية.
  },
  // اختياري: أخفِ العناصر العلوية الخاصة بك أثناء ظهور عملية الالتقاط.
  onWidgetVisibilityChange: (visible) => {},
});

// لإغلاقها بنفسك:
ByUnicoSDK.close();

تتلقى onFinish ما يلي:

الحقل	الوصف
type	'FINISH' عند انتهاء عملية الالتقاط، و'CLOSE' عندما يغلقها الشخص قبل ذلك
transaction.redirectUrl	الوجهة التي يُرسَل إليها الشخص بعد ذلك. موجود فقط مع 'FINISH'

تحذير

تخبرك onFinish بأن عملية الالتقاط انتهت، لا بكيفية انتهائها. تأتي النتيجة فقط من GET /v1/processes/{id} في الواجهة الخلفية لديك.

استخدم onFinish أيضًا لنقل الشخص إلى الشاشة التالية، ولتجنب إنشاء عملية جديدة فورًا إذا بدأ من جديد.

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

• يتعطل التدفق أو يتصرف بشكل غريب. تأكد من أن أيًّا من نصوصك البرمجية لا يعدّل iFrame الخاص بـ SDK في DOM.
• يبدو شكل عملية الالتقاط مختلفًا. قد تصل قواعد CSS العامة، مثل محددات الوسوم، إلى iFrame. تبدأ المعرّفات والفئات الخاصة بـ SDK بالبادئة unico.
• أخطاء غير متوقعة بعد التحديث. ثبّت SDK عبر npm أو yarn فقط، ولا تعدّل ملفاته أبدًا.

الاختبار

أغلق أدوات المطوّر (DevTools) في المتصفح قبل اختبار عملية الالتقاط من البداية إلى النهاية. فتح DevTools يمنع الإرسال.

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

• SDK داخل WebView على الجوال. في التطبيق، افتح link بدلًا من ذلك. راجع أدلة Android وiOS وIonic وReact Native وFlutter.
• عنصر <iframe> خاص بك يشير إلى عملية الالتقاط. استخدم SDK، فهو يدير iFrame.