مدیریت صدور اعتبارنامه با برنامه دارنده شما

برای دریافت و ذخیره کردن اعتبارنامه‌ها از صادرکنندگان، برنامه دارنده شما باید جریان‌های صدور را مدیریت کند. صدور اعتبارنامه می‌تواند به دو روش راه‌اندازی شود:

• جریان آغازشده توسط صادرکننده: کاربر درخواستی را برای صدور کارت پرداخت مجازی از وب‌سایت یا برنامه صادرکننده راه‌اندازی می‌کند. برای مثال، وب‌سایتی ممکن است به کاربرانش گزینه‌ای برای «افزودن گذرنامه به کیف پول» ارائه دهد. صادرکننده Credential Manager issuance API را برای ایجاد درخواست «پیشنهاد مدرک OpenID4VCI» فرامی‌خواند. برای رسیدگی به چنین درخواست‌هایی، دارنده باید ابتدا با «مدیر اطلاعات کاربری» ادغام شود تا فراداده‌هایش را ثبت کند. «مدیر اطلاعات کاربری» گزینه‌های مربوطه را برای انتخاب کاربر نمایش می‌دهد. پس‌از اینکه کاربر گزینه دارنده را انتخاب کرد، برنامه دارنده فراخوانده می‌شود و می‌تواند مراحل لازم برای تکمیل صدور را ادامه دهد.
• جریان آغازشده توسط دارنده: کاربر درخواست می‌کند که یک VDC از برنامه دارنده خود اضافه کند. برای مثال، دارنده ممکن است دکمه‌ای برای «افزودن گذرنامه» ارائه دهد. در این حالت، دارنده فهرست صادرکنندگان پشتیبانی‌شده و فراداده‌هایش را حفظ می‌کند. برای تکمیل این عملکرد، نیازی به ادغام با «مدیر اطلاعات اعتباری Android» ندارد.

برای کسب اطلاعات بیشتر درباره نحوه عملکرد اطلاعات کاربری با Holder API، درباره ذخیره کردن اطلاعات کاربری دیجیتال را ببینید.

سازگاری نسخه Android

«میانای برنامه‌سازی کاربردی دارنده» در Android 6 (سطح میانای برنامه‌سازی کاربردی ۲۳) و بالاتر پشتیبانی می‌شود.

پیاده‌سازی

برای استفاده از Credential Manager Holder API، وابستگی‌های زیر را به دستورگان ساخت ماژول برنامه‌تان اضافه کنید:

dependencies {
    // Use to implement credentials registrys

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

}

dependencies {
    // Use to implement credentials registrys

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

}

ایجاد 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 UI را تعیین کند. برای دیدن نمونه‌ای از تطبیق‌دهنده، به نمونه متن‌باز برنامه کیف پول مراجعه کنید.

رسیدگی به درخواست صدور

سپس، کیف پول باید زمانی را که گزینه ایجاد اطلاعات اعتباری توسط کاربر انتخاب می‌شود مدیریت کند. فعالیتی را تعریف کنید که به فیلتر قصد androidx.credentials.registry.provider.action.CREATE_CREDENTIAL گوش می‌دهد، همان‌طور که در نمونه کیف پول نشان داده شده است.

قصدی که فعالیت را راه‌اندازی می‌کند حاوی درخواست ایجاد و مبدأ تماس است که می‌توانید آن را با تابع 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)
}

تصدیق کلید

درباره تصدیق کلید به موارد زیر توجه کنید:

• هنگام تولید تصدیق کلید، ممکن است از BigInteger.toByteArray برای تبدیل مواد کلید به، برای مثال، کلید وب JSON استفاده کنید. این روش گاهی اوقات می‌تواند یک بایت علامت اضافه کند و باعث خطای اعتبارسنجی شود. اگر این اتفاق افتاد، این بایت‌ها را قبل‌از ارسال تصدیق کلید به صادرکننده بردارید.
• توصیه می‌کنیم از android_key_attestation به‌عنوان نوع اثبات کلید استفاده کنید.

برگرداندن پاسخ ایجاد

وقتی کیف پول مراحل لازم برای ذخیره کردن اطلاعات کاربری را به‌پایان رساند، فعالیت را با پاسخ اطلاعات کاربری به‌پایان برسانید:

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()

برای دیدن نمونه کامل برگرداندن پاسخ اطلاعات کاربری در بافت، به برنامه نمونه مراجعه کنید.