הנפקת פרטי כניסה דיגיטליים

באמצעות Credential Manager API אפשר להנפיק פרטי כניסה לאפליקציות של מחזיקי Android (שנקראות גם "ארנק"). במדריך הזה מוסבר איך להנפיק פרטי כניסה למחזיק המועדף של המשתמש.

הטמעה

בקטע הזה מפורטים השלבים הנדרשים להנפקת אישורים דיגיטליים.

הוספת יחסי תלות

מוסיפים את יחסי התלות הבאים לסקריפט ה-build של 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
        }
    }
}