تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

التعامل مع إصدار المستندات باستخدام تطبيق حامل المستند

لتلقّي بيانات الاعتماد من جهات الإصدار وتخزينها، يجب أن يتعامل تطبيق الحامل مع عمليات الإصدار. يمكن إصدار بيانات الاعتماد بطريقتَين:

عملية يطلقها جهة الإصدار: يرسل المستخدم طلبًا لإصدار بطاقة دفع افتراضية من تطبيق أو موقع إلكتروني تابع لجهة الإصدار. على سبيل المثال، قد يوفّر موقع إلكتروني للمستخدمين خيار "إضافة جواز سفرك إلى محفظتك". تتصل جهة الإصدار بواجهة برمجة التطبيقات لإصدار بيانات الاعتماد في Credential Manager لتقديم طلب عرض بيانات اعتماد OpenID4VCI. للتعامل مع هذه الطلبات، يجب أن يتكامل حامل المستند أولاً مع Credential Manager لتسجيل بياناته الوصفية. سيعرض Credential Manager الخيارات ذات الصلة ليختار منها المستخدم. بعد أن يحدّد المستخدم خيارًا من خيارات تطبيق الحامل، سيتم استدعاء تطبيق الحامل ويمكنه المتابعة في الخطوات اللازمة لإكمال عملية الإصدار.
العملية التي يبدأها حامل البطاقة: يطلب المستخدم إضافة بطاقة دفع افتراضية من تطبيق حامل البطاقة. على سبيل المثال، قد يوفّر حامل البطاقة زرًا "لإضافة جواز سفرك". في هذه الحالة، يحتفظ الحامل بقائمة جهات الإصدار المتوافقة والبيانات الوصفية. ولا يحتاج إلى التكامل مع Android Credential Manager لإكمال هذه الوظيفة.

لمزيد من المعلومات حول آلية عمل بيانات الاعتماد مع Holder API، يُرجى الاطّلاع على لمحة عن تخزين بيانات الاعتماد الرقمية.

التوافق مع إصدارات Android

تتوفّر واجهة برمجة التطبيقات Holder API على الإصدار Android 6 (المستوى 23 من واجهة برمجة التطبيقات) والإصدارات الأحدث.

التنفيذ

لاستخدام واجهة Credential Manager Holder API، أضِف التبعيات التالية إلى النص البرمجي لإنشاء وحدة التطبيق:

رائع

dependencies {
    // Use to implement credentials registrys

    implementation "androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04"

}

Kotlin

dependencies {
    // Use to implement credentials registrys

    implementation("androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04")

}

إنشاء RegistryManager

أنشئ مثيلاً لـ RegistryManager وسجِّل طلب RegisterCreationOptionsRequest معه.

val registryManager = RegistryManager.create(context)

try {
    registryManager.registerCreationOptions(object :
        RegisterCreationOptionsRequest(
            creationOptions = buildIssuanceData(),
            matcher = loadIssuanceMatcher(),
            type = DigitalCredential.TYPE_DIGITAL_CREDENTIAL,
            id = "openid4vci",
        ) {}
    )
} catch (e: Exception) {
    Log.e(TAG, "Issuance registration failed.", e)
}

أداة المطابقة هي ملف ثنائي من WebAssembly (Wasm) يتلقّى creationOptions الذي تم ضبطه أثناء التسجيل وعرض بيانات الاعتماد الذي أرسلته جهة الإصدار لتحديد الإدخالات المعروضة في واجهة مستخدم Credential Manager. يمكنك الرجوع إلى مثال تطبيق المحفظة المفتوح المصدر للاطّلاع على مثال على أداة مطابقة.

التعامل مع طلب إصدار

بعد ذلك، يجب أن تتعامل المحفظة مع خيار إنشاء بيانات الاعتماد الذي يحدّده المستخدم. حدِّد نشاطًا يستمع إلى intent filter androidx.credentials.registry.provider.action.CREATE_CREDENTIAL، كما هو موضّح في نموذج المحفظة.

يحتوي الغرض الذي يطلق النشاط على طلب الإنشاء ومصدر الاستدعاء، ويمكنك استخراجهما باستخدام الدالة PendingIntentHandler.retrieveProviderCreateCredentialRequest. تعرض واجهة برمجة التطبيقات ProviderCreateCredentialRequest يحتوي على جميع المعلومات المرتبطة بطلب الإنشاء. هناك مكوّنان رئيسيان:

التطبيق الذي قدّم الطلب يمكنك استرداد هذا الرمز من خلال getCallingAppInfo.
الطلب من تطبيق الاتصال، ويمكنك استرداده باستخدام getCallingRequest، الذي يعرض CreateCredentialRequest. إذا كان الطلب يتعلّق بمستندات تعريف رقمية، يكون مثيلاً لـ CreateDigitalCredentialRequest، الذي يحتوي على ملف JSON لطلب الإصدار في السمة requestJson. يمكنك معالجة ذلك باستخدام الرمز النموذجي التالي:

val pendingIntentRequest =
    PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
val request = pendingIntentRequest!!.callingRequest
if (request is CreateDigitalCredentialRequest) {
    Log.i(TAG, "Got DC creation request: ${request.requestJson}")
    processCreationRequest(request.requestJson)
}

تصديق المفاتيح

يُرجى ملاحظة ما يلي بشأن تصديق المفاتيح:

عند إنشاء تصديق المفاتيح، قد تستخدم BigInteger.toByteArray لتحويل مواد المفتاح إلى، على سبيل المثال، مفتاح ويب JSON. يمكن أن تضيف هذه الطريقة أحيانًا بايت إشارة وتتسبب في حدوث خطأ في التحقق من الصحة. في هذه الحالة، يجب إزالة وحدات البايت هذه قبل إرسال تصديق المفاتيح إلى جهة الإصدار.
ننصح باستخدام android_key_attestation كنوع إثبات المفتاح.

عرض ردّ الإنشاء

بعد أن تنتهي المحفظة من الخطوات اللازمة لحفظ بيانات الاعتماد، عليك إنهاء النشاط من خلال الردّ على بيانات الاعتماد:

val resultData = Intent()
PendingIntentHandler.setCreateCredentialResponse(
    resultData,
    CreateDigitalCredentialResponse(response.responseJson)
)
setResult(RESULT_OK, resultData)
finish()

إذا كان هناك استثناء، يمكنك إرسال استثناء بيانات الاعتماد بشكل مشابه:

val resultData = Intent()
PendingIntentHandler.setCreateCredentialException(
    resultData,
    CreateCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

للاطّلاع على مثال كامل على عرض ردّ بيانات الاعتماد في السياق، يُرجى الاطّلاع على نموذج التطبيق.

التعامل مع إصدار المستندات باستخدام تطبيق حامل المستند تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.