رابط برنامه‌نویسی کاربردی مدیریت اعتبارنامه - دارنده، برنامه‌های اندروید را قادر می‌سازد تا اعتبارنامه‌های دیجیتال را مدیریت و به تأییدکنندگان ارائه دهند.
شروع کنید
برای استفاده از رابط برنامه‌نویسی کاربردی مدیریت اعتبارنامه - دارنده، وابستگی‌های زیر را به اسکریپت ساخت ماژول برنامه خود اضافه کنید:
// 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
یک کیف پول باید فراداده‌های اعتبارنامه را ثبت کند تا مدیر اعتبارنامه بتواند هنگام دریافت درخواست، آنها را در انتخابگر اعتبارنامه فیلتر و نمایش دهد.
رابط کاربری انتخابگر مدیریت اعتبارنامه
قالب این فراداده به RegisterCredentialsRequest ارسال می‌شود. یک [RegistryManager][1] ایجاد کنید و اعتبارنامه‌ها را ثبت کنید:
در این مثال، فراداده از یک پایگاه داده از ورودی‌های اعتبارنامه‌ها گردآوری شده است. می‌توانید مرجعی را در کیف پول نمونه ما پیدا کنید که فراداده‌ها را در هنگام بارگذاری برنامه ثبت می‌کند. در آینده، ترکیب پایگاه داده اعتبارنامه توسط API جت‌پک پشتیبانی خواهد شد. در آن زمان، می‌توانید فراداده‌های اعتبارنامه را به عنوان ساختارهای داده‌ای کاملاً تعریف‌شده ثبت کنید.
این رجیستری در طول راه‌اندازی مجدد دستگاه همچنان پابرجا می‌ماند. ثبت مجدد همان رجیستری با همان شناسه + نوع، رکورد رجیستری قبلی را رونویسی می‌کند. بنابراین، فقط زمانی که اطلاعات اعتبارنامه شما تغییر کرده است، دوباره ثبت کنید.
اختیاری: ایجاد یک تطبیق‌دهنده
مدیر اعتبارنامه (Credential Manager) مستقل از پروتکل است؛ با رجیستری فراداده به عنوان یک توده مبهم رفتار می‌کند و محتویات آن را تأیید یا بررسی نمی‌کند. بنابراین، کیف پول باید یک تطبیق‌دهنده (matcher) ارائه دهد، یک فایل باینری قابل اجرا که می‌تواند داده‌های خود کیف پول را پردازش کند و فراداده نمایش را بر اساس درخواست ورودی تولید کند. مدیر اعتبارنامه، تطبیق‌دهنده را در یک محیط جعبه شنی (sandbox) بدون دسترسی به شبکه یا دیسک اجرا می‌کند تا قبل از اینکه رابط کاربری برای کاربر رندر شود، هیچ چیزی به کیف پول نشت نکند.
رابط برنامه‌نویسی کاربردی مدیریت اعتبارنامه (Credential Manager API) تطبیق‌دهنده‌هایی برای پروتکل‌های محبوب، مانند OpenID4VP، ارائه می‌دهد. این رابط هنوز رسماً منتشر نشده است، بنابراین فعلاً از تطبیق‌دهنده نمونه ما برای پروتکل OpenID4VP استفاده کنید.
مدیریت اعتبارنامه انتخاب شده
در مرحله بعد، کیف پول باید زمانی که یک اعتبارنامه توسط کاربر انتخاب می‌شود را مدیریت کند. می‌توانید یک فعالیت (Activity) تعریف کنید که به فیلتر اینتنت androidx.credentials.registry.provider.action.GET_CREDENTIAL گوش دهد. کیف پول نمونه ما این رویه را نشان می‌دهد .
اینتنتی که اکتیویتی را اجرا می‌کند شامل درخواست Verifier و فراخوانی origin است که می‌توانید آن را با تابع PendingIntentHandler.retrieveProviderGetCredentialRequest استخراج کنید . API یک ProviderGetCredentialRequest برمی‌گرداند که شامل تمام اطلاعات مرتبط با درخواست verifier است. سه جزء کلیدی وجود دارد:
- برنامه‌ای که درخواست را انجام داده است. می‌توانید این را با
getCallingAppInfoبازیابی کنید. - اعتبارنامه انتخاب شده. شما می‌توانید از طریق متد افزونه
selectedEntryIdاطلاعاتی در مورد اینکه کاربر کدام کاندید را انتخاب کرده است، دریافت کنید؛ این با شناسه اعتبارنامه‌ای که ثبت کرده‌اید مطابقت خواهد داشت. - هر درخواست خاصی که تأییدکننده ارائه داده است. می‌توانید این را از متد
getCredentialOptionsدریافت کنید. در این حالت، می‌توانید انتظار داشته باشید کهGetDigitalCredentialOptionرا در این لیست پیدا کنید که حاوی درخواست Digital Credentials است.
معمولاً، تأییدکننده درخواست ارائه اعتبارنامه دیجیتال را ارسال می‌کند تا بتوانید آن را با کد نمونه زیر پردازش کنید:
request.credentialOptions.forEach { option ->
if (option is GetDigitalCredentialOption) {
Log.i(TAG, "Got DC request: ${option.requestJson}")
processRequest(option.requestJson)
}
}
می‌توانید نمونه‌ای از این را در کیف پول نمونه ما مشاهده کنید.
رابط کاربری کیف پول را رندر کنید
پس از انتخاب اعتبارنامه، کیف پول فراخوانی شده و کاربر از طریق رابط کاربری آن هدایت می‌شود. در نمونه، این یک درخواست بیومتریک است.
پاسخ اعتبارنامه را برگردانید
زمانی که کیف پول آماده ارسال نتیجه شد، می‌توانید با تکمیل فعالیت مربوط به پاسخ اعتبارنامه، این کار را انجام دهید:
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()
برای مثالی از نحوه‌ی برگرداندن پاسخ اعتبارنامه در متن، به برنامه‌ی نمونه مراجعه کنید.