ניהול הנפקת פרטי הכניסה באמצעות אפליקציית המחזיק

כדי לקבל ולאחסן פרטי כניסה מגורמים מנפיקים, אפליקציית המחזיק צריכה לטפל בתהליכי הנפקה. בתהליך הנפקת תעודה, האתר או האפליקציה של הגורם המנפיק שולחים הצעה לתעודה לאפליקציה של המחזיק, עם פירוט המידע שנדרש להקצאת תעודה. אפליקציית המחזיק משתמשת ב-RegistryManager כדי לרשום ב-Credential Manager את סוגי פרטי הכניסה שהיא מתכוונת לטפל בהם. כך האפליקציה תוצג למשתמש והוא יוכל לבחור אותה במהלך בקשת הנפקה כדי לקבל את האישורים.

במאמר מושגי הליבה של Holder API מוסבר איך פרטי הכניסה פועלים עם Holder API.

תאימות לגרסת Android

‫Holder API נתמך ב-Android 6 (רמת API‏ 23) ומעלה.

הטמעה

כדי להשתמש ב-Credential Manager Holder API, מוסיפים את יחסי התלות הבאים לסקריפט ה-build של מודול האפליקציה:

dependencies {
    // Use to implement credentials registrys

    implementation "androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider:1.0.0-alpha04"
    implementation "androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04"

}

dependencies {
    // Use to implement credentials registrys

    implementation("androidx.credentials.registry:registry-digitalcredentials-mdoc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-openid:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-digitalcredentials-sdjwtvc:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider:1.0.0-alpha04")
    implementation("androidx.credentials.registry:registry-provider-play-services:1.0.0-alpha04")

}

יצירת RegistryManager

יוצרים מופע RegistryManager ורושמים בו בקשת RegisterCreationOptionsRequest.

val registryManager = RegistryManager.create(context)

try {
    registryManager.registerCreationOptions(object :
        RegisterCreationOptionsRequest(
            creationOptions = buildIssuanceData(),
            matcher = loadIssuanceMatcher(),
            type = DigitalCredential.TYPE_DIGITAL_CREDENTIAL,
            id = "openid4vci",
        ) {}
    )
} catch (e: Exception) {
    Log.e(TAG, "Issuance registration failed.", e)
}

התאמת המחרוזות היא קובץ בינארי של WebAssembly ‏ (Wasm) שיקבל את הערך creationOptions שהוגדר במהלך הרישום ואת הצעת האישורים שנשלחה על ידי הגורם המנפיק, כדי לקבוע את הרשומות שיוצגו בממשק המשתמש של Credential Manager. דוגמה להתאמה אפשר לראות באפליקציית הארנק בקוד פתוח.

טיפול בבקשה להנפקה

בשלב הבא, הארנק צריך לטפל במצב שבו המשתמש בוחר באפשרות ליצירת אמצעי תשלום. מגדירים פעילות שמקשיבה לandroidx.credentials.registry.provider.action.CREATE_CREDENTIAL מסנן Intent, כמו שמוסבר בארנק לדוגמה.

ה-Intent שמפעיל את הפעילות מכיל את בקשת היצירה ואת מקור הקריאה, שאפשר לחלץ באמצעות הפונקציה PendingIntentHandler.retrieveProviderCreateCredentialRequest. ה-API מחזיר ProviderCreateCredentialRequest שמכיל את כל המידע שמשויך לבקשת היצירה. יש שני רכיבים מרכזיים:

• האפליקציה ששלחה את הבקשה. אפשר לאחזר את הנתונים באמצעות getCallingAppInfo.
• הבקשה מאפליקציית השיחות. אפשר לאחזר אותה באמצעות getCallingRequest, שמחזירה CreateCredentialRequest. אם הבקשה היא לקבלת פרטי כניסה דיגיטליים, היא מופע של CreateDigitalCredentialRequest, שמכיל את בקשת ההנפקה ב-JSON במאפיין requestJson. אפשר לעבד את הנתונים באמצעות הקוד לדוגמה הבא:

val pendingIntentRequest =
    PendingIntentHandler.retrieveProviderCreateCredentialRequest(intent)
val request = pendingIntentRequest!!.callingRequest
if (request is CreateDigitalCredentialRequest) {
    Log.i(TAG, "Got DC creation request: ${request.requestJson}")
    processCreationRequest(request.requestJson)
}

החזרת התגובה ליצירה

אחרי שהארנק ישלים את השלבים שנדרשים לשמירת אמצעי הזיהוי, צריך להשלים את הפעילות עם התגובה של אמצעי הזיהוי:

val resultData = Intent()
PendingIntentHandler.setCreateCredentialResponse(
    resultData,
    CreateDigitalCredentialResponse(response.responseJson)
)
setResult(RESULT_OK, resultData)
finish()

אם יש חריג, אפשר לשלוח את החריג לפרטי הכניסה באופן דומה:

val resultData = Intent()
PendingIntentHandler.setCreateCredentialException(
    resultData,
    CreateCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

כדי לראות דוגמה מלאה להחזרת תגובת האישורים בהקשר, אפשר לעיין באפליקציה לדוגמה.