کروم. هویت

توضیحات

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

مجوزها

identity

انواع

AccountInfo

خواص

  • شناسه

    رشته

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

AccountStatus

کروم ۸۴+

شمارشی

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

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

GetAuthTokenResult

کروم ۱۰۵+

خواص

  • grantScope ها

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

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

  • توکن

    رشته اختیاری

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

InvalidTokenDetails

خواص

  • توکن

    رشته

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

ProfileDetails

کروم ۸۴+

خواص

  • وضعیت حساب

    وضعیت حساب اختیاری

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

ProfileUserInfo

خواص

  • ایمیل

    رشته

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

  • شناسه

    رشته

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

TokenDetails

خواص

  • حساب

    اطلاعات حساب اختیاری

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

  • enableGranularPermissions

    بولی اختیاری

    کروم ۸۷+

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

  • تعاملی

    بولی اختیاری

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

  • محدوده‌ها

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

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

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

WebAuthFlowDetails

خواص

  • abortOnLoadForNonInteractive

    بولی اختیاری

    کروم ۱۱۳+

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

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

  • تعاملی

    بولی اختیاری

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

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

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

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

  • timeoutMsForNonInteractive

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

    کروم ۱۱۳+

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

  • آدرس اینترنتی

    رشته

    URL که جریان احراز هویت را آغاز می‌کند.

روش‌ها

clearAllCachedAuthTokens()

کروم ۸۷+
chrome.identity.clearAllCachedAuthTokens(): Promise<void>

وضعیت API هویت (Identity API) را ریست می‌کند:

  • تمام توکن‌های دسترسی OAuth2 را از حافظه پنهان توکن حذف می‌کند.
  • تنظیمات حساب کاربری را حذف می‌کند
  • کاربر را از تمام جریان‌های احراز هویت محروم می‌کند.

بازگشت‌ها

  • قول<void>

    کروم ۱۰۶+

    یک Promise برمی‌گرداند که پس از پاک شدن وضعیت (state) اجرا می‌شود.

getAccounts()

کانال توسعه‌دهندگان
chrome.identity.getAccounts(): Promise<AccountInfo[]>

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

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

بازگشت‌ها

getAuthToken()

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

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

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

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

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

پارامترها

بازگشت‌ها

  • قول < GetAuthTokenResult >

    کروم ۱۰۵+

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

getProfileUserInfo()

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

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

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

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

پارامترها

بازگشت‌ها

  • کروم ۱۰۶+

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

getRedirectURL()

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

یک URL تغییر مسیر ایجاد می‌کند که در launchWebAuthFlow استفاده خواهد شد.

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

پارامترها

  • مسیر

    رشته اختیاری

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

بازگشت‌ها

  • رشته

launchWebAuthFlow()

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

یک جریان احراز هویت را در URL مشخص شده شروع می‌کند.

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

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

پارامترها

بازگشت‌ها

  • قول <string | undefined>

    کروم ۱۰۶+

    یک Promise برمی‌گرداند که با هدایت مجدد URL به برنامه شما، برطرف می‌شود.

removeCachedAuthToken()

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

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

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

پارامترها

بازگشت‌ها

  • قول<void>

    کروم ۱۰۶+

    یک Promise برمی‌گرداند که پس از حذف توکن از حافظه پنهان، اجرا می‌شود.

رویدادها

onSignInChanged

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

زمانی رخ می‌دهد که وضعیت ورود به سیستم برای یک حساب کاربری در پروفایل کاربر تغییر کند.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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