browser.identity

תיאור

משתמשים ב-API של chrome.identity כדי לקבל טוקני גישה מסוג OAuth2.

הרשאות

identity

סוגים

AccountInfo

מאפיינים

• id [מזהה]

  מחרוזת

  מזהה ייחודי של החשבון. המזהה הזה לא ישתנה כל עוד החשבון קיים.

AccountStatus

‫Chrome 84 ואילך ‫browser.* ‎ מגרסת Chrome 148

טיפוסים בני מנייה (enum)

"SYNC"
מציין שהסנכרון מופעל בחשבון הראשי.

‫"ANY"
מציין את קיומו של חשבון ראשי, אם יש כזה.

GetAuthTokenResult

‫Chrome 105 ואילך ‫browser.* ‎ מ-Chrome 148

מאפיינים

• grantedScopes

  string[] אופציונלי

  רשימה של היקפי הרשאות OAuth2 שניתנו לתוסף.

• token

  מחרוזת אופציונלי

  האסימון הספציפי שמשויך לבקשה.

InvalidTokenDetails

מאפיינים

• token

  מחרוזת

  האסימון הספציפי שצריך להסיר מהמטמון.

ProfileDetails

‫Chrome 84 ואילך ‫browser.* ‎ מגרסת Chrome 148

מאפיינים

• accountStatus

  ‫AccountStatus אופציונלי

  סטטוס של החשבון הראשי שמחובר לפרופיל שצריך להחזיר את ה-ProfileUserInfo שלו. ברירת המחדל היא סטטוס החשבון SYNC.

ProfileUserInfo

מאפיינים

• אימייל

  מחרוזת

  כתובת אימייל של חשבון המשתמש שמחובר לפרופיל הנוכחי. השדה ריק אם המשתמש לא מחובר לחשבון או אם לא צוינה הרשאת המניפסט identity.email.

• id [מזהה]

  מחרוזת

  מזהה ייחודי של החשבון. המזהה הזה לא ישתנה כל עוד החשבון קיים. השדה ריק אם המשתמש לא מחובר לחשבון או (בגרסה M41 ואילך) אם לא צוינה הרשאת המניפסט identity.email.

TokenDetails

מאפיינים

• חשבון

  ‫AccountInfo אופציונלי

  מזהה החשבון שהטוקן שלו אמור להיות מוחזר. אם לא צוין חשבון, הפונקציה תשתמש בחשבון מהפרופיל ב-Chrome: החשבון לסנכרון אם יש כזה, או החשבון הראשון באינטרנט של Google.

• enableGranularPermissions

  בוליאני אופציונלי

  ‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

  הדגל enableGranularPermissions מאפשר לתוספים להצטרף מוקדם למסך ההסכמה להרשאות פרטניות, שבו הרשאות מבוקשות ניתנות או נדחות בנפרד.

• אינטראקטיבי

  בוליאני אופציונלי

  כדי לאחזר אסימון, יכול להיות שהמשתמש יצטרך להיכנס ל-Chrome או לאשר את ההיקפים שהאפליקציה מבקשת. אם הדגל האינטראקטיבי הוא true, getAuthToken יציג למשתמש הנחיות לפי הצורך. כשהדגל הוא false או מושמט, getAuthToken יחזיר כשל בכל פעם שתידרש הנחיה.

• היקפים

  string[] אופציונלי

  רשימה של היקפי הרשאות OAuth2 שצריך לבקש.

  כשהשדה scopes קיים, הוא מבטל את רשימת ההיקפים שצוינה ב-manifest.json.

WebAuthFlowDetails

מאפיינים

• abortOnLoadForNonInteractive

  בוליאני אופציונלי

  ‫Chrome מגרסה 113 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

  האם לסיים את launchWebAuthFlow לבקשות לא אינטראקטיביות אחרי טעינת הדף. הפרמטר הזה לא משפיע על תהליכים אינטראקטיביים.

  כשהערך מוגדר כ-true (ברירת המחדל), התהליך יסתיים מיד אחרי טעינת הדף. כשהמדיניות מוגדרת לערך false, התהליך יסתיים רק אחרי שהערך של timeoutMsForNonInteractive יעבור. ההגדרה הזו שימושית לספקי זהויות שמשתמשים ב-JavaScript כדי לבצע הפניות אוטומטיות אחרי טעינת הדף.

• אינטראקטיבי

  בוליאני אופציונלי

  אם להפעיל את תהליך האימות במצב אינטראקטיבי.

  מכיוון שחלק מתהליכי האימות עשויים להפנות באופן מיידי לכתובת URL של תוצאה, launchWebAuthFlow מסתיר את תצוגת האינטרנט שלו עד שהניווט הראשון מפנה לכתובת ה-URL הסופית, או מסיים לטעון דף שנועד להצגה.

  אם הדגל interactive הוא true, החלון יוצג כשטעינת הדף תושלם. אם הדגל הוא false או שהוא מושמט, הפונקציה launchWebAuthFlow תחזיר שגיאה אם הניווט הראשוני לא ישלים את התהליך.

  בתהליכים שבהם נעשה שימוש ב-JavaScript להפניה אוטומטית, אפשר להגדיר את abortOnLoadForNonInteractive כ-false בשילוב עם הגדרת timeoutMsForNonInteractive כדי לתת לדף הזדמנות לבצע הפניות אוטומטיות.

• timeoutMsForNonInteractive

  מספר אופציונלי

  ‫Chrome מגרסה 113 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

  משך הזמן המקסימלי, באלפיות השנייה, שבו מותר להפעיל את launchWebAuthFlow במצב לא אינטראקטיבי בסך הכול. המדיניות תקפה רק אם המדיניות interactive מוגדרת כ-false.

• url

  מחרוזת

  כתובת ה-URL שמתחילה את תהליך האימות.

Methods

clearAllCachedAuthTokens()

‫Chrome 87 ואילך ‫‎browser.* ‎ מגרסה 148 של Chrome

browser.identity.clearAllCachedAuthTokens(): Promise<void>

איפוס המצב של Identity API:

• הסרה של כל טוקני הגישה מסוג OAuth2 מהמטמון של הטוקנים
• הסרת ההגדרות המועדפות לחשבון של המשתמש
• ביטול ההרשאה של המשתמש מכל תהליכי האימות

החזרות

• Promise<void>

  ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

  הפונקציה מחזירה Promise שנפתר כשהמצב נמחק.

getAccounts()

ערוץ Dev

browser.identity.getAccounts(): Promise<AccountInfo[]>

אחזור רשימה של אובייקטים מסוג AccountInfo שמתארים את החשבונות שקיימים בפרופיל.

התכונה getAccounts נתמכת רק בערוץ הפיתוח.

החזרות

• Promise<AccountInfo[]>

getAuthToken()

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

מקבל טוקן גישה של OAuth2 באמצעות מזהה הלקוח והיקפי ההרשאות שצוינו בקטע oauth2 של manifest.json.

‫Identity API שומר טוקני גישה במטמון בזיכרון, כך שאפשר לקרוא ל-getAuthToken באופן לא אינטראקטיבי בכל פעם שנדרש טוקן. מטמון הטוקנים מטפל באופן אוטומטי בתפוגה.

כדי לספק חוויית משתמש טובה, חשוב שהבקשות לאסימונים אינטראקטיביים יופעלו על ידי ממשק המשתמש באפליקציה, ושהממשק יסביר מה מטרת ההרשאה. אם לא תעשו זאת, המשתמשים יקבלו בקשות הרשאה או מסכי כניסה ל-Chrome אם הם לא מחוברים, ללא הקשר. במיוחד, אל תשתמשו ב-getAuthToken באופן אינטראקטיבי כשהאפליקציה מופעלת בפעם הראשונה.

הערה: כשמפעילים את הפונקציה הזו עם קריאה חוזרת (callback), במקום להחזיר אובייקט, היא תחזיר את שני המאפיינים כארגומנטים נפרדים שמועברים לקריאה החוזרת.

פרמטרים

• פרטים

  ‫TokenDetails אופציונלי

  אפשרויות לאסימונים.

החזרות

• Promise<GetAuthTokenResult>

  ‫Chrome 105 ואילך ‫browser.* ‎ מ-Chrome 148

  הפונקציה מחזירה Promise שמתאים לטוקן גישה מסוג OAuth2, כפי שצוין במניפסט, או נדחה אם הייתה שגיאה. הפרמטר grantedScopes מאוכלס החל מגרסה Chrome 87. כשהפרמטר הזה זמין, הוא מכיל את רשימת ההיקפים שהוקצו שתואמים לאסימון שהוחזר.

getProfileUserInfo()

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

אחזור של כתובת האימייל ומספר חשבון ה-GAIA המעורפל של המשתמש שמחובר לפרופיל.

נדרשת הרשאת המניפסט identity.email. אחרת, מוחזרת תוצאה ריקה.

ה-API הזה שונה מ-identity.getAccounts בשני אופנים. המידע שמוחזר זמין אופליין, והוא רלוונטי רק לחשבון הראשי של הפרופיל.

פרמטרים

• פרטים

  ProfileDetails אופציונלי

  ‫Chrome 84 ואילך ‫browser.* ‎ מגרסת Chrome 148

  אפשרויות הפרופיל.

החזרות

• Promise<ProfileUserInfo>

  ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

  הפונקציה מחזירה Promise שמתקבל עם ProfileUserInfo של החשבון הראשי ב-Chrome, או ProfileUserInfo ריק אם החשבון עם details שצוין לא קיים.

getRedirectURL()

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

יוצרת כתובת URL להפניה אוטומטית לשימוש ב-launchWebAuthFlow.

כתובות ה-URL שנוצרות תואמות לתבנית https://<app-id>.chromiumapp.org/*.

פרמטרים

• נתיב

  מחרוזת אופציונלי

  הנתיב שמתווסף לסוף של כתובת ה-URL שנוצרה.

החזרות

• מחרוזת

launchWebAuthFlow()

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

הפונקציה מתחילה תהליך אימות בכתובת ה-URL שצוינה.

השיטה הזו מאפשרת תהליכי אימות עם ספקי זהויות שאינם של Google, על ידי הפעלת תצוגת אינטרנט וניווט לכתובת ה-URL הראשונה בתהליך האימות של הספק. כשהספק מפנה לכתובת URL שתואמת לתבנית https://<app-id>.chromiumapp.org/*, החלון ייסגר וכתובת ה-URL הסופית להפניה תועבר לפונקציה callback.

כדי לספק חוויית משתמש טובה, חשוב שתהליכי אימות אינטראקטיביים יופעלו על ידי ממשק המשתמש באפליקציה, ושהממשק יסביר מה מטרת האימות. אם לא תעשו את זה, המשתמשים יקבלו בקשות הרשאה בלי הקשר. במיוחד, אל תפעילו תהליך אימות אינטראקטיבי כשהאפליקציה מופעלת בפעם הראשונה.

פרמטרים

• פרטים

  WebAuthFlowDetails

  אפשרויות לתהליך WebAuth.

החזרות

• Promise<string | undefined>

  ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

  הפונקציה מחזירה Promise שמתקבלת עם כתובת ה-URL שהופנתה בחזרה לאפליקציה.

removeCachedAuthToken()

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

מסירה אסימון גישה מסוג OAuth2 מהמטמון של אסימוני Identity API.

אם מתגלה שטוקן גישה לא תקין, צריך להעביר אותו אל removeCachedAuthToken כדי להסיר אותו מהמטמון. לאחר מכן, האפליקציה יכולה לאחזר אסימון חדש באמצעות getAuthToken.

פרמטרים

• פרטים

  InvalidTokenDetails

  פרטי הטוקן.

החזרות

• Promise<void>

  ‫Chrome 106 ואילך browser.* ‎ מגרסה 148 של Chrome

  הפונקציה מחזירה Promise שמתבצעת כשהאסימון מוסר מהמטמון.

אירועים

onSignInChanged

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

מופעל כשמצב הכניסה משתנה בחשבון בפרופיל של המשתמש.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

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

  • חשבון

    AccountInfo

  • signedIn

    בוליאני