حزم SDK للجوال والويب
حزم SDK الأصلية لأنظمة iOS وAndroid وReact Native وFlutter تضع سير العمل داخل تطبيقك وهي المسار الوحيد الذي يدعم NFC. أما حزم SDK للويب فتضمّنه داخل واجهتك الأمامية.
حزم SDK الأصلية متوفرة لأنظمة iOS وAndroid وReact Native وFlutter؛ أما حزم SDK للويب فتضمّن سير العمل داخل واجهتك الأمامية. استخدم حزمة SDK أصلية عندما تحتاج إلى NFC أو أفضل سلوك للكاميرا - فـ WebView لا يمنحك أيًا منهما. النتائج لا تزال تصلك عبر webhook، لا من حزمة SDK نفسها.
#لماذا SDK بدلًا من إعادة توجيه
إعادة التوجيه المستضافة هي أقل جهد، وهي فعليًا مناسبة لمعظم سيناريوهات سير العمل. تستحق حزمة SDK العناء عندما:
- تحتاج إلى NFC. لا يمكن قراءة الرقاقة في جواز السفر أو بطاقة الهوية من صفحة متصفح. حزمة SDK أصلية هي المسار الوحيد. انظر التحقق برقاقة NFC.
- لا تريد أن يغادر المستخدم تطبيقك. إعادة التوجيه إلى الخارج والعودة نقطة تسرّب حقيقية على الجوال.
- تريد أفضل سلوك للكاميرا. الوصول الأصلي إلى الكاميرا أكثر موثوقية من وصول المتصفح، خصوصًا على الأجهزة الأقدم.
#ما هو متاح
| المنصة | ملاحظات |
|---|---|
| iOS | يُوزَّع كـ XCFramework |
| Android | يُوزَّع عبر Maven |
| React Native | يغلّف الوحدات الأصلية؛ يدعم البنية الجديدة (New Architecture) |
| Flutter | يغلّف الوحدات الأصلية |
| JavaScript / الويب | يضمّن سير العمل المستضاف داخل واجهتك الأمامية على الويب |
| iframe داخل السياق | يعرض سير العمل داخل صفحتك بدلًا من إعادة التوجيه |
- اختر منصتك، وتمنحك الصفحة مقتطف تلك المنصة.
- حزم SDK الأصلية والويب، ولكل منها دليل بدء سريع خاص بها، مرتبطة هنا.
تتغير متطلبات الإصدار والحد الأدنى للمنصة مع الإصدارات الجديدة، لذا تحقق من توثيق SDK الحالي بدلًا من لقطة صفحة مساعدة - وإذا كنت على إصدار إطار عمل معيّن (إصدار Expo محدد، مثلًا)، تأكد من التوافق مع جهة الاتصال في Didit قبل الالتزام به في مرحلة عمل.
#WebView ليست حزمة SDK أصلية
تغليف سير العمل المستضاف على الويب داخل WebView يبدو وكأنه يمنحك تجربة داخل التطبيق. إنه يمنحك مظهرها فقط:
- لا يوجد NFC. لا تزال الرقاقة غير قابلة للقراءة.
- أذونات الكاميرا أصعب. يعتمد وصول WebView إلى الكاميرا على إعدادات التطبيق المضيف، والخطأ في ضبطها ينتج بالضبط تقارير "الكاميرا لم تُفتح أبدًا" المذكورة في إصلاح مشكلات فحص الحيوية ومطابقة الوجه.
- اللغة هي لغة التطبيق، لا لغة المستخدم. يُبلغ WebView عن لغة التطبيق المضيف، لذا مرِّر
languageصراحةً عند إنشاء الجلسة. انظر تعيين لغة التحقق.
إذا كنت ستتحمل عناء سير عمل داخل التطبيق، استخدم حزمة SDK الأصلية.
#النتائج لا تزال تصلك عبر webhooks
هذا ما يوقع الناس في الخطأ: تخبر حزمة SDK تطبيقك أن المستخدم أنهى سير العمل. إنها ليست المصدر الموثوق لقرار التحقق.
يُنتَج القرار من جهة الخادم بعد تشغيل الفحوصات، ويصلك عبر webhook. لا تمنح الوصول أبدًا استنادًا إلى استدعاء إتمام حزمة SDK وحده - فالإشارة من جهة العميل يسهل تزويرها، وقد لا تكون الفحوصات قد انتهت حتى عند إطلاقها.
معاملة "حزمة SDK قالت انتهى" كأنها "المستخدم تم التحقق منه" هو الخطأ الأكثر جسامة الممكن في تكامل الجوال. تأكد من ذلك في خادمك، من webhook أو من نقطة نهاية القرار، قبل أن تفتح أي شيء.
#تطبيق مستهلك واحد، أم تطبيقك أنت؟
لا يوجد تطبيق Didit مستهلك منفصل يُسلَّم إليه المستخدمون من جلسة مستضافة لخطوة مثل NFC. إذا أردت كل شيء - NFC وغير NFC - داخل تجربة تطبيق واحدة، فذلك التطبيق هو تطبيقك، مع حزمة SDK مضمَّنة فيه.
#التوزيع وتعارضات الاعتماديات
يتعارض تكامل حزمة SDK الأصلية أحيانًا مع اعتماديات أخرى في التطبيق المضيف - مكتبة متعدية مشتركة، أو subspec يثبّت إصدارًا يثبّته شيء آخر أيضًا. إذا واجهت واحدة من هذه الحالات، فهي مشكلة ملموسة وقابلة للتكرار تستحق الإبلاغ عنها مع ملف اعتمادياتك بدلًا من الالتفاف حولها بتثبيت شيء قديم: الإصلاح عادة ما يكون داخل حزمة SDK نفسها.
#الاختبار على جهاز
يعمل sandbox بنفس الطريقة عبر حزمة SDK كما في أي مكان آخر - وجّه التطبيق إلى مفتاح تطبيق sandbox وكل فحص يُحاكى ولا يُفوتَر. هذه هي الطريقة الصحيحة لتجربة سير عمل الجوال، لأن سلوكيات حزمة SDK التي تحتاج إلى اختبارها أكثر (رسائل الأذونات، دورة حياة الكاميرا، الانتقال إلى الخلفية أثناء الالتقاط) هي سلوكيات جهاز لا تكلّفك شيئًا لتجربتها مرارًا. انظر الاختبار في sandbox.