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

تتيح لك واجهة برمجة التطبيقات Credential Manager API إصدار بيانات الاعتماد لتطبيقات حاملي بيانات الاعتماد على 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)

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

يجب أن يحتوي طلب إنشاء بيانات الاعتماد الرقمية على سلسلة JSON تتوافق مع بروتوكول OpenID4VCI العادي. في ما يلي مثال على شكل طلب 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
        }
    }
}