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

באמצעות 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
        }
    }
}