browser.identity

شرح

از chrome.identity API برای دریافت کدهای دسترسی OAuth2 استفاده کنید.

اجازه‌ها

identity

انواع

AccountInfo

مشخصات

  • id

    رشته

    شناسه یکتای حساب. این شناسه در طول عمر حساب تغییر نخواهد کرد.

AccountStatus

Chrome 84+ browser.* از Chrome 148

شمارشی

«SYNC»
مشخص می‌کند که «همگام‌سازی» برای حساب اصلی فعال است.

«ANY»
وجود حساب اصلی را (درصورت وجود) مشخص می‌کند.

GetAuthTokenResult

Chrome نسخه ۱۰۵ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

مشخصات

  • grantedScopes

    رشته[] اختیاری

    فهرستی از دامنه‌های OAuth2 که به افزونه اعطا شده است.

  • کد

    رشته اختیاری

    نشان خاص مرتبط با درخواست.

InvalidTokenDetails

مشخصات

  • کد

    رشته

    نشان خاصی که باید از حافظه نهان برداشته شود.

ProfileDetails

Chrome 84+ browser.* از Chrome 148

مشخصات

  • accountStatus

    AccountStatus اختیاری

    وضعیت حساب اصلی واردشده به سیستم نمایه‌ای که ProfileUserInfo آن باید برگردانده شود. به‌طور پیش‌فرض روی وضعیت حساب SYNC تنظیم شده است.

ProfileUserInfo

مشخصات

  • ایمیل

    رشته

    نشانی ایمیل برای حساب کاربری که به سیستم نمایه فعلی وارد شده است. اگر کاربر به سیستم وارد نشده باشد یا اجازه مانیفست identity.email مشخص نشده باشد، خالی است.

  • id

    رشته

    شناسه یکتای حساب. این شناسه در طول عمر حساب تغییر نخواهد کرد. اگر کاربر به سیستم وارد نشده باشد یا (در M41+) اجازه مانیفست identity.email مشخص نشده باشد، خالی است.

TokenDetails

مشخصات

  • حساب

    AccountInfo اختیاری

    شناسه حسابی که توکن آن باید برگردانده شود. اگر مشخص نشده باشد، تابع از حسابی از نمایه Chrome استفاده خواهد کرد: حساب «همگام‌سازی» (اگر وجود داشته باشد)، یا درغیراین‌صورت اولین حساب وب Google.

  • enableGranularPermissions

    بولی اختیاری

    Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

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

  • تعاملی

    بولی اختیاری

    برای واکشی کردن یک کد ممکن است لازم باشد کاربر به سیستم Chrome وارد شود یا دامنه‌های درخواستی برنامه را تأیید کند. اگر پرچم تعاملی true باشد، getAuthToken درصورت لزوم از کاربر درخواست خواهد کرد. وقتی پرچم false باشد یا حذف شده باشد، getAuthToken هر زمان که درخواست لازم باشد، شکست را برمی‌گرداند.

  • حوزه‌ها

    رشته[] اختیاری

    فهرستی از دامنه‌های OAuth2 برای درخواست.

    وقتی فیلد scopes وجود داشته باشد، فهرست دامنه‌های مشخص‌شده در manifest.json را لغو می‌کند.

WebAuthFlowDetails

مشخصات

  • abortOnLoadForNonInteractive

    بولی اختیاری

    Chrome نسخه ۱۱۳ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

    آیا launchWebAuthFlow برای درخواست‌های غیرتعاملی پس‌از بار شدن صفحه خاتمه یابد یا نه. این پارامتر بر جریان‌های تعاملی تأثیر نمی‌گذارد.

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

  • تعاملی

    بولی اختیاری

    آیا جریان اصالت‌سنجی در حالت تعاملی راه‌اندازی شود یا نه.

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

    اگر پرچم interactive روی true باشد، وقتی بار کردن صفحه تکمیل شود، پنجره نمایش داده خواهد شد. اگر پرچم false باشد یا حذف شده باشد، اگر پیمایش اولیه جریان را تکمیل نکند، launchWebAuthFlow با خطا برمی‌گردد.

    برای جریان‌هایی که از جاوا اسکریپت برای تغییر مسیر استفاده می‌کنند، abortOnLoadForNonInteractive را می‌توان روی false تنظیم کرد و هم‌زمان timeoutMsForNonInteractive را تنظیم کرد تا به صفحه فرصت داده شود هرگونه تغییر مسیری را انجام دهد.

  • timeoutMsForNonInteractive

    شماره اختیاری

    Chrome نسخه ۱۱۳ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

    حداکثر مدت زمانی (به میلی‌ثانیه) که launchWebAuthFlow درمجموع مجاز است در حالت غیرتعاملی اجرا شود. فقط درصورتی تأثیر دارد که interactive، false باشد.

  • نشانی وب

    رشته

    نشانی وبی که جریان اصالت‌سنجی را آغاز می‌کند.

روش‌ها

clearAllCachedAuthTokens()

Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸ 
browser.identity.clearAllCachedAuthTokens(): Promise<void>

وضعیت Identity API را بازنشانی می‌کند:

  • همه کدهای دسترسی OAuth2 را از حافظه نهان کد برمی‌دارد
  • اولویت‌های حساب کاربر را برمی‌دارد
  • کاربر را از همه جریان‌های اصالت‌سنجی لغو مجوز می‌کند

بازگشتی‌ها

  • Promise<void>

    Chrome 106+ browser.* از Chrome 148

    یک Promise برمی‌گرداند که وقتی وضعیت پاک شد حل می‌شود.

getAccounts()

کانال برنامه‌نویس‌ها 
browser.identity.getAccounts(): Promise<AccountInfo[]>

فهرستی از اشیاء AccountInfo را که حساب‌های موجود در نمایه را توصیف می‌کنند بازیابی می‌کند.

‫getAccounts فقط در کانال برنامه‌نویس‌ها پشتیبانی می‌شود.

بازگشتی‌ها

getAuthToken()

browser.identity.getAuthToken(
  details?: TokenDetails,
): Promise<GetAuthTokenResult>

بااستفاده از شناسه کارخواه و دامنه‌های مشخص‌شده در بخش oauth2 manifest.json، کد دسترسی OAuth2 را دریافت می‌کند.

Identity API کد دسترسی را در حافظه پنهان می‌کند، بنابراین هر زمان که کد دسترسی لازم باشد، می‌توان getAuthToken را به‌صورت غیرتعاملی فراخوانی کرد. حافظه نهان نشان به‌طور خودکار انقضا را مدیریت می‌کند.

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

توجه: وقتی با فراخوانی متقابل تماس گرفته می‌شود، این عملکرد به‌جای برگرداندن شیء، دو ویژگی را به‌عنوان متغیرهای مستقل جداگانه که به فراخوانی متقابل ارسال شده‌اند برمی‌گرداند.

پارامترها

  • جزئیات

    TokenDetails اختیاری

    گزینه‌های کد.

بازگشتی‌ها

  • Chrome نسخه ۱۰۵ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

    یک Promise برمی‌گرداند که با کد دسترسی OAuth2 همان‌طور که توسط مانیفست مشخص شده است حل می‌شود، یا اگر خطایی وجود داشته باشد رد می‌شود. پارامتر grantedScopes از Chrome 87 پر شده است. درصورت دردسترس بودن، این پارامتر حاوی فهرست دامنه‌های اعطاشده مربوط به کد برگردانده‌شده است.

getProfileUserInfo()

browser.identity.getProfileUserInfo(
  details?: ProfileDetails,
): Promise<ProfileUserInfo>

نشانی ایمیل و شناسه gaia مبهم‌شده کاربری را که به سیستم نمایه وارد شده است بازیابی می‌کند.

به اجازه مانیفست identity.email نیاز دارد. درغیراین‌صورت، نتیجه خالی برمی‌گرداند.

این میانای برنامه‌سازی کاربردی از دو جهت با identity.getAccounts متفاوت است. اطلاعات برگردانده‌شده به‌صورت آفلاین دردسترس است و فقط برای حساب اصلی نمایه اعمال می‌شود.

پارامترها

  • جزئیات

    ProfileDetails اختیاری

    Chrome 84+ browser.* از Chrome 148

    گزینه‌های نمایه.

بازگشتی‌ها

  • Promise<ProfileUserInfo>

    Chrome 106+ browser.* از Chrome 148

    یک Promise برمی‌گرداند که با ProfileUserInfo حساب اصلی Chrome حل می‌شود، یا اگر حساب با details داده‌شده وجود نداشته باشد، یک ProfileUserInfo خالی برمی‌گرداند.

getRedirectURL()

browser.identity.getRedirectURL(
  path?: string,
): string

نشانی وب هدایتگری برای استفاده در launchWebAuthFlow تولید می‌کند.

نشانی‌های وب تولیدشده با الگوی https://<app-id>.chromiumapp.org/* مطابقت دارد.

پارامترها

  • مسیر

    رشته اختیاری

    مسیر به انتهای نشانی وب تولیدشده اضافه شد.

بازگشتی‌ها

  • رشته

launchWebAuthFlow()

browser.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
): Promise<string | undefined>

جریان اصالت‌سنجی را در نشانی وب مشخص‌شده شروع می‌کند.

این روش با راه‌اندازی نمای وب و هدایت آن به اولین نشانی وب در جریان اصالت‌سنجی ارائه‌دهنده، جریان‌های اصالت‌سنجی را با ارائه‌دهندگان هویت غیرGoogle فعال می‌کند. وقتی ارائه‌دهنده به نشانی وبی مطابق با الگوی https://<app-id>.chromiumapp.org/* هدایت می‌کند، پنجره بسته می‌شود و نشانی وب هدایتگر نهایی به تابع callback منتقل می‌شود.

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

پارامترها

بازگشتی‌ها

  • Promise<string | undefined>

    Chrome 106+ browser.* از Chrome 148

    یک Promise برمی‌گرداند که با نشانی وب هدایت‌شده به برنامه شما حل می‌شود.

removeCachedAuthToken()

browser.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
): Promise<void>

کد دسترسی OAuth2 را از حافظه نهان کد Identity API برمی‌دارد.

اگر مشخص شود کد دسترسی نامعتبر است، باید به removeCachedAuthToken ارسال شود تا از حافظه نهان برداشته شود. سپس برنامه می‌تواند بااستفاده از getAuthToken، یک کد جدید دریافت کند.

پارامترها

بازگشتی‌ها

  • Promise<void>

    Chrome 106+ browser.* از Chrome 148

    یک Promise برمی‌گرداند که وقتی داده‌واحد از حافظه نهان برداشته شود، حل می‌شود.

رویدادها

onSignInChanged

browser.identity.onSignInChanged.addListener(
  callback: function,
)

وقتی وضعیت ورود به سیستم برای حسابی در نمایه کاربر تغییر می‌کند، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (account: AccountInfo, signedIn: boolean) => void