Credential Manager – API של בעלים

ה-Credential Manager - Holder API מאפשר לאפליקציות ל-Android לנהל ולהציג אישורים דיגיטליים למאמתים.

שנתחיל?

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

// In your app module's build.gradle:
dependencies {
    implementation(libs.androidx.registry.provider)
    implementation(libs.androidx.registry.provider.play.services)
}

// In libs.versions.toml:
registryDigitalCredentials = "1.0.0-alpha02"

androidx-registry-provider = { module = "androidx.credentials.registry:registry-provider", version.ref = "registryDigitalCredentials" }
androidx-registry-provider-play-services = { module = "androidx.credentials.registry:registry-provider-play-services", version.ref = "registryDigitalCredentials" }

רישום פרטי כניסה ב-Credential Manager

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

תמונה שבה מוצג ממשק המשתמש של פרטי הכניסה הדיגיטליים במנהל פרטי הכניסה
איור 1. ממשק המשתמש של פרטי הכניסה הדיגיטליים.

ממשק המשתמש של בורר פרטי הכניסה

הפורמט של המטא-נתונים האלה מועבר אל RegisterCredentialsRequest. יוצרים [RegistryManager][1] ורושמים את פרטי הכניסה:

בדוגמה הזו, המטא-נתונים נאספים ממסד נתונים של רשומות פרטי כניסה. בארנק לדוגמה שלנו יש הפניה שרושמת את המטא-נתונים בטעינת האפליקציה. בעתיד, ממשק Jetpack API יתמוך בהרכבת מסד נתונים של פרטי כניסה. בשלב הזה, אפשר לרשום את המטא-נתונים של פרטי הכניסה כמבני נתונים מוגדרים היטב.

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

אופציונלי: יצירת כלי להתאמת מחרוזות

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

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

טיפול בפרטי כניסה שנבחרו

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

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

  • האפליקציה ששלחה את הבקשה. אפשר לאחזר את הנתונים האלה באמצעות getCallingAppInfo.
  • פרטי הכניסה שנבחרו. אפשר לקבל מידע על המועמד שהמשתמש בחר באמצעות שיטת ההרחבה selectedEntryId. המידע הזה יתאים למזהה האישורים שרשמתם.
  • בקשות ספציפיות שהמאמת הגיש. אפשר לקבל את הנתון הזה באמצעות השיטה getCredentialOptions. במקרה כזה, ברשימה הזו אמורה להופיע בקשה מסוג GetDigitalCredentialOption שקשורה לאישורים דיגיטליים.

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

request.credentialOptions.forEach { option ->
    if (option is GetDigitalCredentialOption) {
        Log.i(TAG, "Got DC request: ${option.requestJson}")
        processRequest(option.requestJson)
    }
}

אפשר לראות דוגמה לכך בארנק לדוגמה.

עיבוד ממשק המשתמש של Wallet

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

החזרת תגובת פרטי הכניסה

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

PendingIntentHandler.setGetCredentialResponse(
    resultData,
    GetCredentialResponse(DigitalCredential(response.responseJson))
)
setResult(RESULT_OK, resultData)
finish()

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

PendingIntentHandler.setGetCredentialException(
    resultData,
    GetCredentialUnknownException() // Configure the proper exception
)
setResult(RESULT_OK, resultData)
finish()

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