Credential Manager - Holder API

تتيح واجهة برمجة التطبيقات Credential Manager - Holder API لتطبيقات Android إدارة بيانات الاعتماد الرقمية وعرضها على مُثبِّتي الهوية.

البدء

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

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha01"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

تسجيل بيانات الاعتماد باستخدام "مدير بيانات الاعتماد"

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

صورة تعرض واجهة مستخدم بيانات الاعتماد الرقمية في "مدير بيانات الاعتماد"
الشكل 1. واجهة مستخدم بيانات الاعتماد الرقمية

واجهة مستخدم أداة اختيار "مدير بيانات الاعتماد"

يتمّ نقل تنسيق هذه البيانات الوصفية إلى RegisterCredentialsRequest. أنشئ [RegistryManager][1] وسجِّل بيانات الاعتماد:

في هذا المثال، يتم تجميع البيانات الوصفية من قاعدة بيانات لإدخالات بيانات الاعتماد. يمكنك العثور على مرجع في نموذج المحفظة الذي يسجِّل البيانات الوصفية عند تحميل التطبيق. في المستقبل، ستتيح Jetpack API تكوين ملف بيانات بيانات الاعتماد. عند هذه المرحلة، يمكنك تسجيل البيانات الوصفية لبيانات الاعتماد كبنى بيانات محدّدة جيدًا.

تظل قاعدة بيانات المسجّلين محفوظة عند إعادة تشغيل الجهاز. سيؤدي إعادة تسجيل السجلّ نفسه الذي يحتوي على المعرّف والنوع نفسهما إلى استبدال سجلّ السجلّ السابق. لذلك، لن تحتاج إلى إعادة التسجيل إلا عند تغيير بيانات بيانات الاعتماد.

اختياري: إنشاء أداة مطابقة

لا يعتمد "مدير بيانات الاعتماد" على بروتوكول معيّن، بل يتعامل مع قاعدة بيانات البيانات الوصفية على أنّها كتلة بيانات غير شفافة ولا يتحقق من محتوياتها أو يتحقّق منها. لذلك، على المحفظة توفير أداة مطابقة، وهي ملف ثنائي قابل للتنفيذ يمكنه معالجة بيانات المحفظة الخاصة وإنشاء البيانات الوصفية المعروضة استنادًا إلى طلب وارد. سيشغِّل "مدير بيانات الاعتماد" أداة المطابقة في بيئة وضع الحماية بدون الوصول إلى الشبكة أو القرص، وذلك لكي لا يتم تسرُّب أي بيانات إلى محفظة قبل عرض واجهة المستخدم للمستخدم.

ستوفّر واجهة برمجة التطبيقات Credential Manager API أدوات مطابقة للبروتوكولات الشائعة، مثل OpenID4VP. لم يتم طرحه رسميًا بعد، لذا يمكنك في الوقت الحالي استخدام نموذج المطابق الخاص بنا لبروتوكول OpenID4VP v24.

التعامل مع بيانات اعتماد محدّدة

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

سيحتوي Intent الذي يطلق النشاط على طلب Verifier و مصدر الاستدعاء، ويمكن استخراجه باستخدام الدالة PendingIntentHandler.retrieveProviderGetCredentialRequest. تعرض واجهة برمجة التطبيقات ProviderGetCredentialRequest يتضمّن كل المعلومات المرتبطة بطلب التحقّق المحدّد. هناك ثلاثة مكوّنات رئيسية:

  • التطبيق الذي قدّم الطلب. يمكنك استرداد هذا الرمز باستخدام getCallingAppInfo.
  • بيانات الاعتماد التي تم اختيارها يمكنك الحصول على معلومات عن المرشح الذي اختَره المستخدم من خلال طريقة إضافة selectedEntryId، وسيتطابق مع معرّف بيانات الاعتماد الذي سجّلته.
  • أي طلبات محدّدة قدّمها المدقّق يمكنك الحصول على هذه البيانات من خلال الأسلوب getCredentialOptions. في هذه الحالة، من المفترض أن يظهر لك رمز GetDigitalCredentialOption في هذه القائمة يحتوي على طلب ملف الاعتماد الرقمي.

في أغلب الأحيان، سيطلب منك المدقّق عرض المستندات الرقمية حتى تتمكّن من معالجتها باستخدام نموذج الرمز البرمجي التالي:

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

يمكنك الاطّلاع على مثال على ذلك في نموذج المحفظة.

عرض واجهة مستخدم المحفظة

بعد اختيار بيانات الاعتماد، يتمّ استدعاء المحفظة ويتم توجيه المستخدِم من خلال واجهة المستخدم. في المثال، هذا طلب لاستخدام المقاييس الحيوية.

عرض ردّ بيانات الاعتماد

عندما تصبح المحفظة جاهزة لإرسال النتيجة، يمكنك إجراء ذلك من خلال إنهاء النشاط باستخدام ردّ بيانات الاعتماد:

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

في حال توفّر استثناء، يمكنك إرسال استثناء بيانات الاعتماد بالطريقة نفسها:

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

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