هنگام راه‌اندازی دستگاه جدید، اعتبار برنامه را بازیابی کنید

قابلیت بازیابی اعتبارنامه‌ها در Credential Manager به کاربران اجازه می‌دهد تا هنگام راه‌اندازی یک دستگاه جدید، حساب‌های برنامه خود را بازیابی کنند. این API در پیش‌نمایش توسعه‌دهندگان است و در تمام دستگاه‌هایی که اندروید ۹ یا بالاتر و نسخه ۲۴۲۲۰۰۰۰۰ یا بالاتر از سرویس‌های گوگل پلی (GMS) Core دارند، در دسترس است. مزایای قابلیت بازیابی اعتبارنامه‌ها شامل موارد زیر است:

• تجربه کاربری یکپارچه : کاربران می‌توانند حساب برنامه خود را بدون نیاز به ورود دستی به هر برنامه جداگانه، بازیابی کنند.
• افزایش تعامل کاربر : اگر کاربران بتوانند هنگام راه‌اندازی دستگاه جدید، حساب کاربری خود را بازیابی کنند، احتمال بیشتری وجود دارد که به استفاده از برنامه شما ادامه دهند.
• کاهش تلاش برای توسعه : ویژگی بازیابی اعتبارنامه‌ها با مدیریت اعتبارنامه‌ها یکپارچه شده است، بنابراین توسعه‌دهندگانی که از قبل از کلیدهای عبور پشتیبانی می‌کنند، می‌توانند قابلیت‌های بازیابی اعتبارنامه را اضافه کنند.

چگونه کار می‌کند؟

شما می‌توانید از Restore Credentials برای ایجاد، دریافت و پاک کردن اعتبارنامه‌های مربوطه استفاده کنید.

1. ایجاد اعتبارنامه بازیابی : وقتی کاربر وارد برنامه شما می‌شود، یک اعتبارنامه بازیابی مرتبط با حساب کاربری او ایجاد کنید. این اعتبارنامه به صورت محلی ذخیره می‌شود و در صورتی که کاربر Google Backup را فعال کرده باشد و رمزگذاری سرتاسری در دسترس باشد، با فضای ابری همگام‌سازی می‌شود (برنامه‌ها می‌توانند از همگام‌سازی با فضای ابری انصراف دهند).
2. دریافت اعتبارنامه بازیابی : وقتی کاربر دستگاه جدیدی را راه‌اندازی می‌کند، برنامه شما می‌تواند از Credential Manager درخواست بازیابی اعتبارنامه را بدهد. این به شما امکان می‌دهد کاربر را بدون نیاز به هیچ ورودی اضافی، به طور خودکار وارد سیستم کنید.
3. پاک کردن اعتبار بازیابی : وقتی کاربر از برنامه شما خارج می‌شود، باید اعتبار بازیابی مرتبط را حذف کنید.

ویژگی بازیابی اعتبارنامه‌ها می‌تواند به راحتی با سیستم‌های پشتیبان که از قبل کلیدهای عبور را پیاده‌سازی کرده‌اند، ادغام شود. این سازگاری از این واقعیت ناشی می‌شود که هم کلیدهای عبور و هم کلیدهای بازیابی (نوع اعتبارنامه‌ای که توسط ویژگی بازیابی اعتبارنامه‌ها استفاده می‌شود) از مشخصات فنی اساسی یکسانی پیروی می‌کنند. این هماهنگی تضمین می‌کند که فرآیند بازیابی اعتبارنامه‌ها می‌تواند به طور مؤثر اعتبارنامه‌های کاربر ذخیره شده در سیستم‌های دارای کلید عبور را بازیابی و بازیابی کند و یک تجربه سازگار و کاربرپسند را در پلتفرم‌ها و روش‌های احراز هویت مختلف ارائه دهد.

پیاده‌سازی

رابط برنامه‌نویسی کاربردی بازیابی اطلاعات احراز هویت (Restore Credentials API) از طریق کتابخانه Credential Manager Jetpack در دسترس است. برای شروع، این مراحل را دنبال کنید:

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

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-beta03")
}

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-beta03"
}

1. یک شیء CreateRestoreCredentialRequest ایجاد کنید.

2. متد createCredential() را روی شیء CredentialManager فراخوانی کنید.

   val credentialManager = CredentialManager.create(context)
   
   // On a successful authentication create a Restore Key
   // Pass in the context and CreateRestoreCredentialRequest object
   val response = credentialManager.createCredential(context, createRestoreRequest)
   

   این اعتبارنامه‌ی بازیابی تولید شده، نوعی اعتبارنامه‌ی webauthn است و به عنوان کلید بازیابی شناخته می‌شود.

3. وقتی کاربر یک دستگاه جدید را راه‌اندازی می‌کند، متد getCredential() را روی شیء CredentialManager فراخوانی کنید.

   // Fetch the Authentication JSON from server
   val authenticationJson = fetchAuthenticationJson()
   
   // Create the GetRestoreCredentialRequest object
   val options = GetRestoreCredentialOption(authenticationJson)
   val getRequest = GetCredentialRequest(listOf(options))
   
   // The restore key can be fetched in two scenarios to
   // 1. On the first launch of app on the device, fetch the Restore Key
   // 2. In the onRestore callback (if the app implements the Backup Agent)
   val response = credentialManager.getCredential(context, getRequest)
   

4. وقتی کاربر از برنامه شما خارج می‌شود، متد clearCredentialState() را روی شیء CredentialManager فراخوانی کنید.

   // Create a ClearCredentialStateRequest object
   val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)
   
   // On user log-out, clear the restore key
   val response = credentialManager.clearCredentialState(clearRequest)
   

اگر از یک عامل پشتیبان استفاده می‌کنید، بخش getCredential را در فراخوانی onRestore انجام دهید. این کار تضمین می‌کند که اعتبارنامه‌های برنامه بلافاصله پس از بازیابی داده‌های برنامه بازیابی می‌شوند.

سوالات متداول

سوال ۱: تفاوت بین کلید بازیابی و کلید عبور چیست؟

کلید بازیابی عملکردی مشابه کلید عبور دارد، اما به‌طور خاص برای بازیابی حساب کاربری در دستگاه‌های جدید طراحی شده است. وقتی از یک مدیر رمز عبور مانند Google Password Manager برای تأیید اعتبار استفاده می‌کنید، کلیدهای عبور و رمزهای عبور قابل استفاده شما نمایش داده می‌شوند، در حالی که کلید بازیابی نمایش داده نمی‌شود، زیرا برای ورودهای معمولی در نظر گرفته نشده است.

سوال ۲: آیا کلید بازیابی، یک اعتبارنامه یکبار مصرف است؟

خیر، کلید بازیابی یک اعتبارنامه‌ی یک‌بار مصرف نیست. Credential Manager بدون وضعیت (stateless) است و از فعالیت کاربر بی‌اطلاع است، بنابراین نمی‌تواند پس از استفاده، کلید را به‌طور خودکار حذف کند.

کلیدهای بازیابی فقط در شرایط زیر حذف می‌شوند:

• اقدامات سطح سیستم : کاربران برنامه را حذف نصب می‌کنند یا داده‌های آن را پاک می‌کنند.
• فراخوانی‌های سطح برنامه : شما با فراخوانی CredentialManager#clearCredentialState() هنگام مدیریت خروج کاربر در کد برنامه، کلید را به صورت برنامه‌نویسی حذف می‌کنید.

سوال ۳. آیا ویژگی بازیابی اطلاعات ورود (Restore Credentials) فقط برای دستگاه جدید کار می‌کند؟

بله، این ویژگی برای راه‌اندازی اولیه یک دستگاه جدید مبتنی بر اندروید طراحی شده است، زیرا مستقیماً به عملکرد پشتیبان‌گیری و بازیابی سیستم گره خورده است.

سوال ۴. آیا می‌توانم از قابلیت بازیابی اطلاعات کاربری (Restore Credentials) برای ورود بی‌سروصدا به حساب کاربری در هر دستگاهی که همان حساب گوگل در آن وارد شده است، استفاده کنم؟

خیر، قابلیت بازیابی اطلاعات کاربری (Restore Credentials) برای ورود عمومی به سیستم در دستگاه‌های مختلف در نظر گرفته نشده است. این قابلیت فقط در یک سناریوی خاص کار می‌کند: زمانی که کاربر با بازیابی نسخه پشتیبان از دستگاه قدیمی خود، دستگاه جدیدی را راه‌اندازی می‌کند. برای موفقیت‌آمیز بودن این فرآیند بازیابی یکباره، هر دو دستگاه باید به یک حساب گوگل متصل باشند.

سوال ۵. سازمان من یک برنامه اصلی و چندین برنامه فرعی دارد. آیا می‌توان برای همه این برنامه‌ها کلید بازیابی را فعال کرد؟

خیر. کلید بازیابی به نام بسته‌ی منحصر به فرد هر برنامه وابسته است. از آنجایی که برنامه‌ی اصلی و هر زیربرنامه نام بسته‌ی متفاوتی دارند، باید برای هر برنامه یک کلید بازیابی جداگانه ایجاد کنید.

س۶: آیا برای ایجاد کلید بازیابی برای حساب کاربری، به رمز عبور نیاز است؟

خیر، نیازی به رمز عبور نیست. قابلیت ایجاد کلید بازیابی مستقل از روش ورود کاربر است. هدف آن ذخیره وضعیت احراز هویت فعلی کاربر است. تا زمانی که کاربر به طور فعال وارد برنامه شما شده باشد، می‌توانید برای او یک کلید بازیابی ایجاد کنید.

سوال ۷: آیا کاربر می‌تواند کلید بازیابی را حذف کند؟

خیر، کاربر هیچ کنترل مستقیمی بر کلید بازیابی ندارد. منطق برنامه مسئول مدیریت کلیدهای بازیابی است.

برای امنیت، توصیه می‌کنیم برنامه هر زمان که کاربر از سیستم خارج می‌شود، کلید را به‌طور خودکار حذف کند. این کار تضمین می‌کند که دفعه بعد که برنامه را در همان دستگاه باز می‌کنند، به درستی از سیستم خارج شده و از آنها خواسته می‌شود دوباره وارد سیستم شوند.

سوال ۸: آیا می‌توانم بدون تنظیم allowBackup روی true در مانیفست، از Restore Credentials استفاده کنم؟

بله، ویژگی Restore Credentials صرف نظر از اینکه allowBackup روی true تنظیم شده باشد یا خیر، کار می‌کند.

سوال ۹. بازیابی اطلاعات کاربری برای کاربرانی که چندین حساب کاربری وارد شده در یک برنامه دارند، چگونه کار می‌کند؟

ویژگی بازیابی اطلاعات کاربری (Restore Credentials) به گونه‌ای طراحی شده است که فقط با یک حساب کاربری در یک زمان کار کند.