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

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

لمزيد من المعلومات حول طريقة عمل بيانات الاعتماد مع Holder API، يُرجى قراءة المفاهيم الأساسية لواجهة Holder API.

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

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

التنفيذ

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

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"

}

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". يمكنك الرجوع إلى مثال تطبيق المحفظة المفتوح المصدر للاطّلاع على مثال على أداة مطابقة.

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

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

يتضمّن الغرض الذي يبدأ النشاط طلب الإنشاء ومصدر الاستدعاء، ويمكنك استخراجهما باستخدام الدالة 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)
}

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

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

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

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