اعتبارنامه‌هایتان را با ارائه‌دهندگان اعتبارنامه سازگار نگه دارید

وقتی کاربر گذرکلید ایجاد می‌کند، سرور طرف متکی جزئیات خاصی را ذخیره می‌کند، درحالی‌که ارائه‌دهنده اطلاعات کاربری، مانند «مدیر گذرواژه Google»، جزئیات دیگری را ذخیره می‌کند. به‌طور دقیق:

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

ناهماهنگی‌های احتمالی بین داده‌های ذخیره‌شده در سرور طرف تکیه‌کننده و ارائه‌دهنده اطلاعات کاربری می‌تواند به تجربه کاربری بد منجر شود. ممکن است در سناریوهای زیر مشکلاتی پیش بیاید:

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

Signal API در Credential Manager به طرف‌های متکی اجازه می‌دهد با ارائه‌دهندگان اطلاعات کاربری ارتباط برقرار کنند تا اطلاعات کاربری را حذف کنند و فراداده‌های کاربر را به‌روزرسانی کنند، مانند نام کاربری و نام نمایشی. سه نوع درخواست پشتیبانی‌شده برای سناریوهای مختلف وجود دارد:

  • SignalUnknownCredentialRequest

    • نشان می‌دهد که اعتبارنامه خاصی دیگر معتبر نیست و باید از ارائه‌دهنده اعتبارنامه پنهان یا برداشته شود.
  • SignalAllAcceptedCredentialIdsRequest

    • فهرستی از شناسه‌های اطلاعات اعتباری پذیرفته‌شده را به ارائه‌دهنده اطلاعات اعتباری ارائه می‌دهد.
  • SignalCurrentUserDetailsRequest

    • جزئیات فراداده کاربر را به‌روز می‌کند.

سازگاری نسخه

‫Signal API در دستگاه‌های دارای Android 15 یا بالاتر دردسترس است و از نسخه 1.6.0-beta03 کتابخانه androidx.credentials دردسترس است.

پیاده‌سازی

برای استفاده از Signal API، این مراحل را دنبال کنید:

  1. وابستگی Credential Manager را به پروژه‌تان اضافه کنید.

    کاتلین

    dependencies {
        implementation("androidx.credentials:credentials:1.7.0-alpha03")
    }

    شیار

    dependencies {
        implementation "androidx.credentials:credentials:1.7.0-alpha03"
    }

  2. فراخوانی Signal API

    برای ارسال درخواست سیگنال به ارائه‌دهنده اطلاعات کاربری، از درخواست سیگنال پشتیبانی‌شده استفاده کنید. هریک از انواع درخواست سیگنال به درخواست JSON نیاز دارد، همان‌طور که در مثال‌های زیر نشان داده شده است:

    • اطلاعات کاربری نامشخص (SignalUnknownCredentialRequest)

      از SignalUnknownCredentialRequest برای نشان دادن اینکه طرف اعتمادکننده شناسه اطلاعات اعتباری را تشخیص نمی‌دهد استفاده کنید. وقتی ارائه‌دهنده اطلاعات کاربری این سیگنال را دریافت می‌کند، اطلاعات کاربری را پنهان یا حذف می‌کند.

      استفاده

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

      پارامترهای JSON موردنیاز برای این درخواست rpId و credentialId هستند. برای اطلاعات بیشتر درباره ساختار JSON، گزینه‌های signalUnknownCredential را ببینید.

      credentialManager.signalCredentialState(
          SignalUnknownCredentialRequest(
              requestJson = JSONObject().apply {
                  put("rpId", rpId /* [String] RP ID of the relying party */)
                  put("credentialId", credentialId /* [String] Credential ID of the credential to be hidden or deleted */)
              }.toString()
          )
      )
      
    • همه اطلاعات کاربری پذیرفته‌شده (SignalAllAcceptedCredentialIdsRequest)

      از SignalAllAcceptedCredentialIdsRequest برای اطلاع‌رسانی به ارائه‌دهندگان اعتبارنامه با مجموعه همه اعتبارنامه‌های پذیرفته‌شده استفاده کنید. وقتی ارائه‌دهنده اطلاعات اعتباری سیگنال را دریافت می‌کند، ارائه‌دهنده اطلاعات اعتباری هرگونه اطلاعات اعتباری را که در این فهرست گنجانده نشده است پنهان یا حذف می‌کند، یا هرگونه اطلاعات اعتباری را که قبلاً پنهان شده است و اکنون در فهرست گنجانده شده است آشکار می‌کند.

      استفاده

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

      پارامترهای JSON لازم برای این درخواست عبارتند از rpId، userId، و allAcceptedCredentialIds. برای اطلاعات بیشتر درباره ساختار JSON، گزینه‌های signalAllAcceptedCredential را ببینید.

      credentialManager.signalCredentialState(
          SignalAllAcceptedCredentialIdsRequest(
              requestJson = JSONObject().apply {
                  put("rpId", rpId /* [String] RP ID of the relying party */)
                  put("userId", userId /* [String] User ID of the current user */)
                  put(
                      "allAcceptedCredentialIds",
                      JSONArray(credentialIdsList /* [List<String>] List of accepted Credential IDs */)
                  )
              }.toString()
          )
      )
      
    • جزئیات کاربر فعلی (SignalCurrentUserDetailsRequest)

      از SignalCurrentUserDetailsRequest برای مطلع کردن ارائه‌دهندگان اطلاعات کاربری استفاده کنید که فراداده، مانند نام کاربری و نام نمایشی برای کاربر مشخص، به‌روز شده است و باید در ارائه‌دهنده اطلاعات کاربری نشان داده شود.

      استفاده

      وقتی کاربر یا طرف متکی فراداده گذرکلید منسوب به حساب کاربری را به‌روز می‌کند، از این سیگنال استفاده کنید.

      پارامترهای JSON لازم برای این درخواست عبارت‌اند از rpId،‏ userId،‏ name، و displayName. برای اطلاعات بیشتر درباره ساختار JSON، گزینه‌های signalCurrentUserDetails را ببینید.

      credentialManager.signalCredentialState(
          SignalCurrentUserDetailsRequest(
              requestJson = JSONObject().apply {
                  put("rpId", rpId /* [String] RP ID of the relying party */)
                  put("userId", userId /* [String] User ID of the current user */)
                  put("name", name /* [String] New Name to be updated for the current user */)
                  put("displayName", displayName /* [String] New display name to be updated for the current user */)
              }.toString()
          )
      )
      

آزمایش پیاده‌سازی

برای آزمایش پیاده‌سازی Signal API، مراحل زیر را تکمیل کنید:

  1. نمونه ارائه‌دهنده اطلاعات اعتباری با نام MyVault را نصب کنید.

  2. MyVault را به‌عنوان ارائه‌دهنده اطلاعات کاربری در تنظیمات > گذرواژه‌ها، گذرکلیدها و حساب‌ها > سرویس ترجیحی فعال کنید.

    منو «سرویس ترجیحی» در تنظیمات Android که MyVault را به‌عنوان ارائه‌دهنده اطلاعات کاربری فعال نشان می‌دهد.

  3. همه اعلان‌های MyVault را در تنظیمات > برنامه‌ها > MyVault > اعلان‌ها فعال کنید.

    منوِ «اعلان‌ها» برای برنامه MyVault، که نشان می‌دهد همه اعلان‌ها فعال شده‌اند.

  4. مطمئن شوید که نمایش روی صفحه برای اعلان‌ها در تنظیمات > برنامه‌ها > MyVault > اعلان‌ها > دسته‌ها > کانال اعلان Signal API روشن باشد.

    تنظیمات «کانال اعلان Signal API» برای MyVault، که گزینه «نمایش روی صفحه» را در حالت فعال نشان می‌دهد.

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