قبول Google Wallet ID في مسار تسجيل المستخدمين: دليل التكامل
كيفية قبول Google Wallet ID مع Didit: بيئة الاختبار أولاً، والتسجيل لدى Google لمرة واحدة، والمسار المستضاف أو API المستقل، وتطبيقات Android، والبديل بالمستندات، وقراءة النتيجة المتحقق منها.

باختصار
لقبول Google Wallet ID في مسار تسجيل المستخدمين لديك، ابدأ البناء في sandbox أولاً، وسجّل كل تطبيق إنتاجي لدى Google مرة واحدة من لوحة تحكم Didit، ثم فعّل Google Wallet لبلد ما في سير عمل أو استدعِ API المستقل من صفحتك الخاصة أو تطبيق Android.
- المسار المستضاف: قم بتفعيل Google Wallet في خطوة التحقق من الهوية وأبقِ التقاط المستندات كخيار بديل.
- API المستقل: ابدأ من خادمك الخلفي، واطلب من المحفظة ضمن نقرة المستخدم، وأرسل استجابة المحفظة مرة واحدة.
- لا تعتمد إلا النتيجة المكتملة والمتحقق منها والمقروءة من خادمك الخلفي كإثبات للهوية.
هذا الدليل موجه للمطور الذي يكتب التكامل ولمدير المنتج الذي يضعه في عملية التسجيل. ويغطي كلتا الطريقتين لقبول Google Wallet ID مع Didit: المسار المستضاف وAPI المستقل. لمعرفة ما تم إطلاقه ولماذا يعد مهماً، اقرأ التحقق من Google Wallet ID. لمعرفة معيار المتصفح الأساسي، اقرأ دليلنا حول Digital Credentials API.
يشارك الشخص بطاقة هوية تم إنشاؤها من جواز سفر أو، في الولايات المتحدة، رخصة قيادة رقمية على الهاتف المحمول من ولاية مدعومة، من Google Wallet أو محفظة Android متوافقة أخرى. تقبل Didit ذلك في خمس دول: الولايات المتحدة والمملكة المتحدة والبرازيل وسنغافورة وتايوان.[1]
طريقتان لقبول Google Wallet ID
تعيد كلتاهما السمات نفسها التي تم التحقق منها ونتيجة signature_valid نفسها.[1]
الأسرع في الإطلاق
المسار المستضاف (Sessions API)
- تعرض Didit خيار "Verify with digital ID" فقط عندما يدعم المتصفح والجهاز ذلك
- تعمل قواعد سير العمل والبديل بالمستندات في الجلسة نفسها
- قم بتضمينه باستخدام Web SDK أو iframe
تدير Didit الشاشات
تحكم كامل
API المستقل
- تطلب صفحتك أو تطبيق Android الخاص بك من المحفظة مباشرة
- لا يوجد سير عمل، ولا
workflow_id، ولاreturn_url - أنت تبني الزر وإعادة المحاولة وأي خيار بديل
تدير واجهة المستخدم لديك الشاشات
يأتي المسار المستضاف مع البديل بالمستندات مدمجاً مسبقاً. ويستخدم تطبيق Android الأصلي أو شاشة التسجيل المخصصة API المستقل.
قبل أن تبدأ
حدد هذه الأمور قبل كتابة التعليمات البرمجية.
- أنشئ تطبيقاً في sandbox: فهو لا يتطلب التسجيل لدى Google ولا يخصم أي رصيد.[2]
- دوّن أصل HTTPS الذي سيطلب من المحفظة، مثل
https://app.example.com. - سجّل مضيف هذا الأصل كاسم مضيف للعودة لتطبيقك، أو استخدم نطاق علامتك البيضاء.[2]
- احتفظ بمفتاح API على خادمك الخلفي: يحمل كل استدعاء لـ Didit الترويسة
x-api-keyويتم من جانب الخادم.
ترفض المحفظة أي طلب يأتي من أصل غير الأصل الذي بدأت به، لذا فإن الأصل ليس تفصيلاً يمكن تسويته لاحقاً.[2] تقبل Didit Google Wallet في خمس دول.
| الدولة | قيمة API | بيانات الاعتماد التي يمكن للأشخاص مشاركتها |
|---|---|---|
| الولايات المتحدة | USA | بطاقة هوية من جواز سفر، رخصة قيادة على الهاتف المحمول من الولايات الأمريكية المدعومة |
| المملكة المتحدة | GBR | بطاقة هوية من جواز سفر |
| البرازيل | BRA | بطاقة هوية من جواز سفر |
| سنغافورة | SGP | بطاقة هوية من جواز سفر |
| تايوان | TWN | بطاقة هوية من جواز سفر |
الدول وقيم API لـ Google Wallet على Didit.[1][2]
الخيار 1: المسار المستضاف
في المسار المستضاف، تُعد Google Wallet طريقة إضافية في خطوة التحقق من الهوية (ID Verification) ضمن سير العمل. في لوحة التحكم، افتح سير العمل، وانتقل إلى ID Verification، واختر دولة مدعومة ثم فعّل Google Wallet بين المحافظ المقبولة. عبر API، تأتي على شكل كتلة wallet لكل دولة:
{"USA": {"document": {"enabled": true}, "wallet": {"enabled": true, "providers": ["google_wallet"], "on_failure": "fallback_to_document"}}}
إن wallet.providers هي قائمة قبول وليست ترتيباً تفضيلياً: يختار الشخص من بين ما قبلته أنت.[1] تحدد wallet.on_failure ما يحدث عندما لا تنتهي خطوة المحفظة بنتيجة تم التحقق منها.
1إنشاء جلسة
يستدعي خادمك الخلفي واجهة Sessions API مع سير العمل.
2تتحقق Didit من المتصفح
تُتاح الطريقة فقط عندما يمكن للمتصفح والجهاز طلب محفظة.
يشارك الشخص هوية رقمية
تم التحقق
تصل السمات الموقعة إلى الجلسة.
اتبع on_failure
التقاط المستند، أو عملية ID Verification مرفوضة.
3قراءة القرار
إشعار Webhook أو نتيجة الجلسة، على خادمك الخلفي.
المسار المستضاف مع Google Wallet كطريقة أولى.
تضمين المسار المستضاف في iframe
إذا فُتح المسار المستضاف داخل صفحتك، يجب السماح للمتصفح بطلب المحفظة من داخل الإطار. استخدم Web SDK 0.5.1 أو أحدث، أو أضف digital-credentials-get إلى سمة allow الخاصة بعنصر iframe.[1][5]
تنبيه
بدون digital-credentials-get، يرفض المتصفح طلب المحفظة داخل iframe.
ما يظهره المسار المستضاف للمستخدمين
لا توجد إعادة توجيه. يؤكد الشخص في نافذة المحفظة الخاصة بالمتصفح أو بنظام Android، والتي تعرض اسم شركتك وشعارها. على متصفح سطح المكتب، يُنشئ المتصفح رمز QR الخاص به ليتمكن الشخص من الاستجابة عبر المحفظة على هاتفه.[1][2] يحمل الزر نص "Verify with digital ID"، نظراً لأن أي محفظة متوافقة على Android يمكنها الاستجابة، وتظهر عليه أيقونة محفظة عامة.
الخطوة 1
في خطوة الهوية، يختار الشخص الخيار المعنون بـ "Verify with digital ID".
1يختار الشخص خيار الهوية الرقمية.
الخطوة 2
يفتح المتصفح أو Android نافذة المحفظة الخاصة به، والتي تتضمن اسمك وشعارك، ويوافق الشخص على المشاركة عبر هاتفه.
2نافذة المحفظة تابعة للمتصفح أو لنظام Android.
الخطوة 3
إذا أغلق الشخص النافذة، تعرض الصفحة عبارة "Your wallet did not finish" وتتيح خياري "Try again" أو "Scan your ID instead".
3إلغاء النافذة يؤدي إلى إعادة المحاولة أو مسح المستند ضوئياً.
الخطوات بالشرح. رسم تخطيطي وليس صورة لشاشة فعلية؛ التسميات المقتبسة هي الصياغة النصية الخاصة بالمسار المستضاف.
الخيار 2: API المستقل، خطوة بخطوة
مع API المستقل، تطلب صفحتك أو تطبيق Android من المحفظة مباشرة، عبر W3C Digital Credentials API.[7] لا توجد صفحة مستضافة من Didit ولا رمز QR من Didit.[2]
يضغط الشخص على مشاركة
طلب Google Wallet المستقل. لا يغادر مفتاح API خادمك الخلفي أبداً.
الخطوة 1: ابدأ بالأصل الخاص بك
يستدعي خادمك الخلفي POST /v3/id-verification/wallets/google-wallet/ باستخدام x-api-key وIdempotency-Key ونص JSON يتضمن country وorigin. يمكنك إضافة vendor_data (مرجع عميلك، حتى 2,000 بايت بتنسيق UTF-8) وmetadata.[2][3]
{"country": "USA", "origin": "https://app.example.com", "vendor_data": "your-customer-reference"}
تحمل الاستجابة request_id، وwallet_verification.interaction = "digital_credentials" وnext_action.type = "request_digital_credential". مرّر next_action.digital_credentials.request إلى الصفحة.
الخطوة 2: اطلب المحفظة ضمن إجراء مباشر من المستخدم
استدعِ navigator.credentials.get({digital: request}) من معالج النقر لزر “Verify with digital ID”، على الأصل الذي بدأت به. يجب أن يعمل الاستدعاء ضمن إجراء مباشر من المستخدم، لذا لا تضع خطوة غير متزامنة بين النقر والاستدعاء: اجلب الطلب قبل النقر.[2] أظهر الزر فقط حيث يمكن للمتصفح طلب المحفظة، على سبيل المثال عندما يكون التعبير "DigitalCredential" in window صحيحاً.
ملاحظة
المطالبة الملغاة تفشل بالخطأ NotAllowedError أو AbortError؛ ويعني NotSupportedError أن هذا المتصفح لا يستطيع مخاطبة محفظة. اربط الإلغاء بإعادة المحاولة وبمسار المستندات لديك؛ وحيث لا يستطيع المتصفح مخاطبة محفظة، أخفِ الخيار.[2]
الخطوة 3: إرسال استجابة المحفظة
أرسل ما أرجعته المحفظة، {protocol, data}، إلى خادمك الخلفي. ومن هناك، استدعِ POST /v3/id-verification/wallets/verifications/{request_id}/response/ مع النص {"response": {...}}. أرسل لمرة واحدة: فالإرسال لمرة ثانية يُرجع التحقق المحسوم بالفعل.[2][4]
وراء هذا الاستدعاء، تتحقق Didit من توقيع الجهة المصدرة مقابل جذور الجهات المصدرة الموثوقة، ومن كل قيمة مُرجعة مقابل ملخصها الموقّع، وتوقيع الجهاز على أصلك وهذا الطلب.[4]
تطبيقات Android
يستخدم تطبيق Android الأصلي Jetpack Credential Manager بالطلب نفسه.[2][8] أنشئ GetDigitalCredentialOption من next_action.digital_credentials.request، واستدعِ getCredential، وأرسل credentialJson المُرجع إلى خادمك الخلفي كنص response.[2]
الأصل مختلف. بدلاً من أصل HTTPS، أرسل android:apk-key-hash: متبوعاً بقيمة SHA-256 بتنسيق base64 لشهادة توقيع تطبيقك، دون حشو.[2]
| الخطأ | المكان | الإجراء المطلوب |
|---|---|---|
origin_invalid | البدء، 400 | أرسل أصل HTTPS أو أصل تطبيق Android |
origin_not_allowed | البدء، 400 | سجّل المضيف كاسم مضيف للعودة |
not_a_digital_credentials_wallet | إرسال، 409 | لا يقبل هذا التحقق استجابة من المحفظة |
الأخطاء الثلاثة التي يجب معالجتها في التكامل المستقل.[2]
معالجة النتيجة وإشعارات webhook
استجابة الإرسال هي نتيجة التحقق المحسومة. يمكنك أيضاً قراءتها عبر GET /v3/id-verification/wallets/verifications/{request_id}/، أو استلامها في إشعار webhook الخاص بـ status.updated مع webhook_version: "v3". يتطابق session_id في webhook مع request_id، وتظهر هوية المحفظة مع verification_method: "wallet".[2] تحقق من توقيع webhook واجعل المعالج غير حساس للتكرار: تُعاد محاولة عمليات التسليم الفاشلة.
| الحقل | ما يوضحه لك |
|---|---|
full_name، date_of_birth | حقول الهوية الموحدة في نتيجة التحقق من الهوية |
wallet_verification.attributes | document_number و document_expiry_date والبيانات المشتركة الأخرى |
signature_valid | قرار Didit بشأن الإقرار الموقع، والذي يتم التحقق منه داخل Didit ولا يُعاد إرساله |
assurance | cryptographic: الدليل هو بيانات اعتماد موقعة |
| مستوى الضمان | جوهري |
portrait | null: لا تشارك Google Wallet صورة شخصية، لذا لا توجد مطابقة للوجه معها |
ما يعيده التحقق المكتمل عبر Google Wallet. يتم إرجاع الجنسية لبطاقة الهوية فقط.[1]
بيانات الاعتماد التي تفشل ليست استجابة خطأ. إنها عملية تحقق محسومة بالنتيجة failed.[2] في المسار المستضاف، تقود النتائج نفسها wallet.on_failure.
| النتيجة | المعنى | تتم فوترته |
|---|---|---|
verified | شارك الشخص الهوية وتم التحقق من صحة السمات الموقعة | نعم |
cancelled | تراجع الشخص عن مطالبة المحفظة | لا |
timeout | انتهت صلاحية نافذة تسجيل الدخول (10 دقائق افتراضياً للمحافظ) | لا |
failed | لم يكتمل تسجيل الدخول أو لم يتم التحقق من صحة الإقرار | لا |
نتائج المحفظة والفوترة.[1]
تنبيه
العودة من المتصفح أو القيمة المرسلة من صفحتك ليست إثباتاً للهوية. لا تعتمد الحساب إلا بناءً على نتيجة verified مكتملة قرأها خادمك الخلفي من Didit، عبر API أو عبر إشعار webhook موقّع.[2]
إعداد خيار المستندات البديل
لا يملك كل شخص هوية رقمية، ولا يمكن لكل متصفح مخاطبة محفظة. يُخفي المسار المستضاف الطريقة عندما يتعذر على المتصفح إجراء الطلب، ويحتفظ بالتقاط المستندات.[1] عند ضبط on_failure على fallback_to_document، فإن أي محاولة محفظة ملغاة أو منتهية الصلاحية أو فاشلة توجّه الشخص إلى التقاط المستندات في الجلسة نفسها. ومع decline، تنتهي الجلسة برفض ID Verification. وإذا كان التقاط المستندات معطلاً لذلك البلد، فإن fallback_to_document يؤدي أيضاً إلى الرفض، لعدم وجود خيار بديل للرجوع إليه.[1]

خطوة التقاط المستندات التي يصل إليها الشخص بعد "Scan your ID instead".
في API المستقل تقع هذه الخطوة على عاتقك: اعرض التحقق من المستند عندما لا تكون النتيجة verified.
الاختبار في sandbox
يُشغّل تطبيق sandbox نفس الخطوات المتبعة في الإنتاج باستخدام محفظة محاكاة. تتضمن الاستجابات simulated: true، وتحدد أي استجابة مرسلة نتيجة التحقق، ولا تُخصم أي أرصدة. الموافقة المحاكاة هي بيانات تجريبية وليست هوية تم التحقق منها.[2]
sandbox_scenario | ما يختبره |
|---|---|
wallet_cancelled | إعادة المحاولة والخيار البديل لديك عند تراجع الشخص |
wallet_timeout | طلب منتهي الصلاحية |
wallet_provider_error | محفظة لا تكتمل |
سيناريوهات sandbox. ترفض التطبيقات المباشرة sandbox_scenario.[2]
الانتقال إلى التشغيل الفعلي: التسجيل لدى Google
يُسجّل كل تطبيق إنتاجي لدى Google مرة واحدة. تعرض لوحة التحكم عبارة "يعمل في sandbox الآن. سجّل لدى Google قبل الانتقال إلى التشغيل الفعلي." على تطبيق sandbox. وإلى أن يُسجّل تطبيق الإنتاج، يُرفض حفظ أي سير عمل يُفعّل Google Wallet برسالة "سجّل هذا التطبيق لدى Google قبل تفعيل Google Wallet."[1]
1افتح خطوة ID Verification
في لوحة التحكم، ابحث عن صف Google Wallet لبلد مدعوم.
2اختر Register with Google
يفتح مربع الحوار "Register with Google Wallet". يمكن للمسؤول (Admin) فقط إرساله.
3املأ خمسة حقول
اسم الكيان القانوني، والاسم المعروض في Google Wallet، وشعار مربع، ورابط سياسة الخصوصية، والغرض.
4مسجل
تنتقل الشارة من "بحاجة إلى تسجيل" إلى "جارٍ التسجيل" ثم إلى "مسجّل".
يستغرق الإعداد لمرة واحدة نحو دقيقة؛ وتوضح لوحة التحكم أنه يكون جاهزاً عادةً في غضون بضع دقائق.[1]
يشرح مربع الحوار الخطوة في سطر واحد: "تسجل Didit شركتك لدى Google بصفتها جهة التحقق الخاصة بك. تحتاج Google إلى هذا الإجراء مرة واحدة قبل أن يتمكن المستخدمون من مشاركة Google Wallet ID الخاص بهم معك." يقبل الاسم المعروض في Google Wallet حتى 64 حرفاً؛ والشعار عبارة عن ملف PNG أو JPG مربع بحجم لا يقل عن 256 x 256 px. ويعرض مربع الحوار أيضاً معاينة لما سيشاركه الأشخاص.
كيف تساعدك Didit على قبول Google Wallet ID
تدير Didit طلب المحفظة، والتسجيل لدى Google، والفحوصات، والبديل بالمستندات عبر API واحد، إلى جانب محافظ الهوية الرقمية الأخرى التي تدعمها. تبلغ تكلفة التحقق من Google Wallet ID $0.20 لكل عملية تحقق مكتملة وفقاً للسعر المعلن. لا يتم فرض رسوم على عمليات تسجيل الدخول الملغاة أو منتهية الصلاحية أو المرفوضة أو غير المكتملة، كما يُعد البديل بالمستندات فحصاً منفصلاً تتم فوترته بأسعار التحقق من المستندات (الأسعار).[6] في لوحة التحكم: Workflows ثم ID Verification ثم Countries ثم Wallets accepted.
ما تقدمه Didit
- طلب المحفظة الموقع والتسجيل لدى Google
- فحوصات جهة الإصدار والملخص الرقمي وتوقيع الجهاز
- المسار المستضاف، وsandbox، والبديل بالمستندات
- التحقق المحسوم عبر API وwebhook
ما يبقى من مسؤوليتك
- الأصول الخاصة بك، وأسماء مضيفي العودة، ومفتاح API
- الزر، وإعادة المحاولة، والنصوص في واجهة المستخدم الخاصة بك
- البلدان والنتائج التي تقبلها
- قرار التسجيل وسياسة الامتثال الخاصة بك
أضف Google Wallet إلى عملية التسجيل الخاصة بك
ابدأ البناء في sandbox اليوم، وسجّل لدى Google مرة واحدة، وادفع فقط مقابل الفحوصات المكتملة.
النقاط الرئيسية
- لا يتطلب sandbox أي تسجيل؛ يُسجّل كل تطبيق إنتاجي لدى Google مرة واحدة، من لوحة التحكم.
- يقدم المسار المستضاف خيار “Verify with digital ID” فقط حيثما يعمل، ويحتفظ بالتقاط المستندات كبديل.
- في iframe، اسمح بـ
digital-credentials-getأو استخدم Web SDK 0.5.1 أو الأحدث. - لا يُعد إثباتاً للهوية إلا نتيجة
verifiedمكتملة قرأها خادمك الخلفي.
الأسئلة الشائعة
هل أحتاج إلى سير عمل لاستخدام Google Wallet؟
لا. لا يحتاج API المستقل إلى سير عمل ولا إلى workflow_id. يستخدم المسار المستضاف سير عمل، حيث يتم تفعيل Google Wallet لكل بلد على حدة.
ما الأصل الذي أرسله لتطبيق Android؟
أرسل android:apk-key-hash: متبوعاً بـ SHA-256 بترميز base64 لشهادة توقيع تطبيقك، دون حشو. يرسل موقع الويب أصل HTTPS الخاص بصفحته.
لماذا يفشل طلب المحفظة داخل iframe الخاص بي؟
يرفض المتصفح الطلب ما لم يسمح iframe بذلك. أضف digital-credentials-get إلى سمة allow الخاصة بـ iframe، أو استخدم Web SDK 0.5.1 أو أحدث.
هل يمكنني إرسال استجابة المحفظة مرتين؟
يتم إرسال الاستجابة مرة واحدة. الإرسال للمرة الثانية يعيد التحقق الذي تم البت فيه بالفعل.
كيف تبدو بيانات الاعتماد الفاشلة في API؟
إنها عملية تحقق تم البت فيها مع النتيجة failed، وليست استجابة خطأ. في المسار المستضاف، تتبع wallet.on_failure.
كيف أختبر دون Google Wallet ID حقيقي؟
استخدم تطبيق sandbox. فهو يحاكي نفس الخطوات، ويعيد simulated: true، ولا يخصم أي رصيد، وتتيح sandbox_scenario اختبار حالات الفشل.
كيف تتعرف إشعارات webhook على التحقق من المحفظة؟
يتطابق session_id الخاص بـ webhook لـ status.updated مع request_id من API المحفظة، وتحمل هوية المحفظة verification_method: "wallet". استخدم webhook_version: "v3" وتحقق من التوقيع.
ماذا يحدث إذا اختلف أصل صفحتي عن الأصل الذي بدأت به؟
ترفض المحفظة الطلب. ابدأ التحقق بالأصل الدقيق الذي سيطلب من المحفظة، وسجل مضيفه كاسم مضيف للعودة لتطبيقك.
المصادر
- محافظ الهوية الرقمية: Google Wallet، والفشل والبدائل، والتسعير، وثائق Didit، تمت القراءة في 20 نوفمبر 2026.
- APIs محافظ الهوية الرقمية: محافظ Digital Credentials (Google Wallet)، وwebhooks، وsandbox، وثائق Didit، تمت القراءة في 20 نوفمبر 2026.
- مرجع API: Google Wallet، وثائق Didit، تمت القراءة في 20 نوفمبر 2026.
- إرسال استجابة محفظة الهوية الرقمية، وثائق Didit، تمت القراءة في 20 نوفمبر 2026.
- تكامل iframe في السياق، وثائق Didit، تمت القراءة في 20 نوفمبر 2026.
- التسعير، وثائق Didit، تمت القراءة في 20 نوفمبر 2026.
- Digital Credentials API: هوية آمنة وخاصة على الويب، Chrome for Developers، 3 أكتوبر 2025.
- التحقق من بيانات الاعتماد الرقمية، Android Developers.
تنطبق نفس الأنماط على التحقق من eID أيضاً. للاطلاع على كل محفظة يمكنك قبولها، ابدأ من محافظ الهوية الرقمية على Didit.
قبول Google Wallet ID مع Didit
فعّل "Verify with digital ID" في سير عمل، أو استدعِ API المحفظة من صفحتك الخاصة.
مقالات ذات صلة
- Google Wallet ID مقابل التحقق من وثائق الهوية: متى تستخدم كلاً منهما
- شرح Digital Credentials API: كيف تصل المواقع إلى محافظ الهوية
- قبول Google Wallet ID في مسار تسجيل المستخدمين: دليل التكامل
- بطاقة Google Wallet ID pass: ما تتلقاه الشركات وأين تعمل
- التحقق من الهوية عبر Google Wallet متاح الآن على Didit
- 7 أفضل منصات البرمجيات eIDAS في عام 2026