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

يمكن استخدام عملية إثبات صحة بيانات الاعتماد الرقمية في تطبيقات Android لمصادقة هوية مستخدم (مثل مستند تعريف هوية صادر عن جهة حكومية) وتفويضه، أو إثبات صحة بيانات عن ذلك المستخدم (مثل رخصة قيادة أو درجة أكاديمية أو سمات مثل العمر أو العنوان)، أو في سيناريوهات أخرى يجب فيها إصدار بيانات اعتماد وإثبات صحتها لإثبات صحة هوية جهة معيّنة.

بيانات الاعتماد الرقمية هي معيار حاضنة مفتوح المصدر من W3C الذي يحدد كيفية الوصول إلى بيانات الاعتماد الرقمية القابلة للتحقّق الخاصة بالمستخدم من محفظة رقمية، ويتم تنفيذه لحالات استخدام الويب باستخدام واجهة برمجة التطبيقات W3C Credential Management API. على أجهزة Android، يتم استخدام واجهة برمجة التطبيقات DigitalCredential في أداة "إدارة بيانات الاعتماد" لإثبات صحة بيانات الاعتماد الرقمية.

التنفيذ

لإثبات صحة بيانات الاعتماد الرقمية في مشروع Android، اتّبِع الخطوات التالية:

1. أضِف التبعيات إلى نص إنشاء تطبيقك وابدأ فئة CredentialManager.
2. أنشئ طلبًا لبيانات اعتماد رقمية واستخدِمه لبدء استخدام DigitalCredentialOption، ثم أنشئ GetCredentialRequest.
3. ابدأ عملية getCredential باستخدام الطلب الذي تم إنشاؤه لتلقّي GetCredentialResponse ناجحة أو معالجة أي استثناءات قد تحدث. بعد استرداد البيانات بنجاح، تحقّق من الاستجابة.

إضافة التبعيات وبدء التشغيل

أضِف التبعيات التالية إلى نص إنشاء Gradle البرمجي:

dependencies {
    implementation("androidx.credentials:credentials:1.5.0-beta01")
    implementation("androidx.credentials:credentials-play-services-auth:1.5.0-beta01")
}

بعد ذلك، يمكنك إعداد مثيل لفئة CredentialManager.

val credentialManager = CredentialManager.create(context)

إنشاء طلب بيانات اعتماد رقمية

أنشئ طلبًا لبيانات اعتماد رقمية واستخدِمه لبدء استخدام DigitalCredentialOption.

// The request in the JSON format to conform with
// the JSON-ified Digital Credentials API request definition.
val requestJson = generateRequestFromServer()
val digitalCredentialOption =
    GetDigitalCredentialOption(requestJson = requestJson)

// Use the option from the previous step to build the `GetCredentialRequest`.
val getCredRequest = GetCredentialRequest(
    listOf(digitalCredentialOption)
)

الحصول على بيانات الاعتماد

ابدأ عملية getCredential باستخدام الطلب الذي تم إنشاؤه. ستتلقّى إما GetCredentialResponse في حال نجاح الطلب، أو GetCredentialException في حال تعذّر تنفيذه.

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

coroutineScope.launch {
    try {
        val result = credentialManager.getCredential(
            context = activityContext,
            request = getCredRequest
        )
        verifyResult(result)
    } catch (e : GetCredentialException) {
        handleFailure(e)
    }
}

// Handle the successfully returned credential.
fun verifyResult(result: GetCredentialResponse) {
    val credential = result.credential
    when (credential) {
        is DigitalCredential -> {
            val responseJson = credential.credentialJson
            validateResponseOnServer(responseJson)
        }
        else -> {
            // Catch any unrecognized credential type here.
            Log.e(TAG, "Unexpected type of credential ${credential.type}")
        }
    }
}

// Handle failure.
fun handleFailure(e: GetCredentialException) {
  when (e) {
        is GetCredentialCancellationException -> {
            // The user intentionally canceled the operation and chose not
            // to share the credential.
        }
        is GetCredentialInterruptedException -> {
            // Retry-able error. Consider retrying the call.
        }
        is NoCredentialException -> {
            // No credential was available.
        }
        is CreateCredentialUnknownException -> {
            // An unknown, usually unexpected, error has occurred. Check the
            // message error for any additional debugging information.
        }
        is CreateCredentialCustomException -> {
            // You have encountered a custom error thrown by the wallet.
            // If you made the API call with a request object that's a
            // subclass of CreateCustomCredentialRequest using a 3rd-party SDK,
            // then you should check for any custom exception type constants
            // within that SDK to match with e.type. Otherwise, drop or log the
            // exception.
        }
        else -> Log.w(TAG, "Unexpected exception type ${e::class.java}")
    }
}