إصدار بيانات اعتماد رقمية

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

التنفيذ

يوضّح هذا القسم الخطوات المطلوبة لإصدار مستندات اعتماد رقمية.

إضافة التبعيات

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

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha02"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02"
}

تهيئة Credential Manager

تهيئة مثيل للفئة CredentialManager

val credentialManager = CredentialManager.create(context)

إنشاء طلب إصدار

يجب أن يتضمّن طلب إنشاء المستند الرقمي اعتمادًا على معيار OpenID4VCI سلسلة JSON. في ما يلي مثال على شكل طلب OpenID4VCI:

"requests": [
  {
    "protocol": "openid4vci-v1",
    "data": {
      "credential_issuer": "https://digital-credentials.dev",
      "credential_configuration_ids": [
        "com.emvco.payment_card"
      ],
      "grants": {
        "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
          "pre-authorized_code": "..."
        }
      }
    }
  }
]

أنشئ CreateDigitalCredentialRequest يحتوي على طلب الإصدار.

val issuanceRequestJson = "{ ... }" // Your issuance JSON
val createRequest = CreateDigitalCredentialRequest(
    requestJson = issuanceRequestJson,
    origin = null
)

تقديم طلب الإصدار

أصدِر بيانات الاعتماد إلى حاملها باستخدام الدالة createCredential. تُطلق هذه الدالة أداة اختيار ورقة Credential Manager السفلية التي تتيح للمستخدم اختيار تطبيق حامل بيانات الاعتماد الذي يريد تخزين بيانات الاعتماد فيه.

try {
    val response = credentialManager.createCredential(
        context = context,
        request = createRequest
    )
    handleSuccess(response as CreateDigitalCredentialResponse)
} catch (e: CreateCredentialException) {
    handleCreateException(e)
}

التعامل مع الردّ

بعد تقديم طلب إصدار الشهادة، سيتم عرض CreateDigitalCredentialResponse. تحتوي هذه الاستجابة على السلسلة responseJson التي تصف نتيجة الإصدار.

fun handleSuccess(response: CreateDigitalCredentialResponse) {
    val responseJson = response.responseJson
    // Parse responseJson according to your protocol (e.g. OpenID4VCI)
}

التعامل مع الاستثناءات

في حال تعذّر إكمال عملية إصدار البطاقة، يعرض createCredential الرمز CreateCredentialException، ويجب أن يتعامل تطبيقك مع هذا الرمز:

fun handleCreateException(e: CreateCredentialException) {
    when (e) {
        is CreateCredentialCancellationException -> {
            // The user canceled the flow
        }
        is CreateCredentialInterruptedException -> {
            // The flow was interrupted (e.g. by another UI element)
        }
        is CreateCredentialNoCreateOptionException -> {
            // No wallet application is available to handle the request
        }
        is CreateCredentialUnsupportedException -> {
            // The device or the system doesn't support this request
        }
        is CreateCredentialProviderConfigurationException -> {
            // There is a configuration issue with the wallet provider
        }
        is CreateCredentialCustomException -> {
            // A protocol-specific error occurred
            val errorType = e.type
            val errorMessage = e.message
        }
        is CreateCredentialUnknownException -> {
            // An unknown error occurred
        }
        else -> {
            // Generic error handling
        }
    }
}