رحلات المستخدم

رحلات المستخدم هي جلسات التقاط متعددة الخطوات تنسِّقها SDK بالتزامن مع التدفق المهيَّأ. على سبيل المثال، يُنفِّذ تدفق idchecktrustdocssign صورة شخصية + مستند + توقيع في جلسة واحدة.

حالات الاستخدام

تعتمد الرحلات المتاحة على التدفق المهيَّأ لتكاملك. راجع حالات الاستخدام للاطلاع على الخريطة الكاملة: حالة الاستخدام → التدفق → القدرة.

How it works

يُفوِّض المكوِّن الإضافي إلى SDKs الأصلية الأساسية:

1. يفتح المكوِّن الإضافي الكاميرا (Android أو iOS) مع تراكب SmartFrame.
2. تُنسِّق SDK الأصلية تسلسل الالتقاطات المطلوبة للتدفق (صورة شخصية، مستند، توقيع).
3. تُحيل SDK النتائج داخلياً إلى Unico — لا يتلقى العميل بيانات الصور ولا يديرها مباشرة.
4. يُعيد كائن SuccessResult مع processId عبر قناة المنصة.

يتم التعامل مع التنسيق بالكامل بواسطة SDK — ليست هناك حاجة إلى تنفيذ تسلسل الخطوات في كود Dart الخاص بك.

Camera mode (smart capture)

يمتلك SDK الإطارة الذكية والالتقاط التلقائي مفعَّلَين بشكل افتراضي. قم بتهيئة وضع الكاميرا في المنشئ الخاص بك على النحو التالي:

UnicoCheckCameraOpener _opener = new UnicoCheck(this)
    .setAutoCapture(autoCapture: true)
    .setSmartFrame(smartFrame: true)
    .build();

نصيحة

قيم false/true للأساليب أعلاه لا تغير تجربة الالتقاط؛ تُستخدم فقط للمنطق الداخلي لـ SDK.

Starting a User Journey

الخطوة 1 — تنفيذ UnicoListener

يتولى UnicoListener معالجة استدعاءات دورة حياة SDK. نفِّذ الأساليب الأربعة الإلزامية:

الأسلوب	متى يُستدعى
onErrorUnico(error)	حدث خطأ أثناء تشغيل SDK
onUserClosedCameraManually()	أغلق المستخدم الكاميرا يدوياً
onSystemClosedCameraTimeoutSession()	تم الوصول إلى حد الجلسة البالغ 40 ثانية
onSystemChangedTypeCameraTimeoutFaceInference()	لم يُكتشف أي وجه لمدة 13 ثانية — ينتقل إلى الالتقاط اليدوي

class _MyHomePageState extends State<MyHomePage> implements UnicoListener {
  late UnicoCheckBuilder _unicoCheck;

  @override
  void onErrorUnico(UnicoError error) {}

  @override
  void onUserClosedCameraManually() {}

  @override
  void onSystemClosedCameraTimeoutSession() {}

  @override
  void onSystemChangedTypeCameraTimeoutFaceInference() {}
}

أساليب المستمع الإلزامية

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

الخطوة 2 — تنفيذ مستمعات الرحلة على UnicoSelfie

أضف استدعاءات الرحلة إلى فئة الحالة الخاصة بك:

الأسلوب	الوصف
onSuccess(SuccessResult result)	نجح الالتقاط — يُعيد SuccessResult مع processId (تعالج Unico الصورة داخلياً)
onErrorSelfie(UnicoError error)	فشل الالتقاط — يُعيد UnicoError مع الرمز والوصف

لا توجد بيانات صورة

على خلاف تدفق التحقق من الحيوية، لا يُعيد استدعاء رحلة المستخدم base64 أو encrypted. تعالج Unico بيانات الصورة داخلياً وتُعيد فقط processId.

@override
void onSuccess(SuccessResult result) {
  debugPrint('processId: ${result.processId}');
}

@override
void onErrorSelfie(UnicoError error) { }

الخطوة 3 — استدعاء openCameraSelfie

يفتح أسلوب openCameraSelfie الكاميرا. لرحلات المستخدم، مرِّر webAppToken المقدَّم من Unico بدلاً من ملف بيانات اعتماد JSON:

_opener.openCameraSelfie(
  listener: this,
  webAppToken: token,
);

Monitoring data collection

يوفر أسلوب openCameraSelfie تحميلاً زائداً يقبل بيانات وصفية عبر UnicoCheckPrepareInfo للمساعدة في تحديد جلسة المستخدم والتدفق:

• externalUserId (String، مطلوب) — معرِّف المستخدم في نظامك. يُجزَّأ تلقائياً باستخدام SHA-256 قبل الإرسال.
• useCase (String، اختياري) — معرِّف للسياق أو التدفق الجاري تشغيله حالياً. يُرسَل بنص عادي.

_opener.openCameraSelfie(
  listener: this,
  webAppToken: token,
  prepareInfo: UnicoCheckPrepareInfo(
    externalUserId: 'external_user_id',
    useCase: 'use_case', // optional
  ),
);

للاطلاع على المعالجة الكاملة للنتيجة، راجع استقبال النتيجة.