chrome.identity

תיאור

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

הרשאות

identity

סוגים

AccountInfo

מאפיינים

• id [מזהה]

  מחרוזת

  מזהה ייחודי של החשבון. המזהה הזה לא ישתנה במהלך חיי החשבון.

AccountStatus

‫Chrome 84 ואילך

Enum

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

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

GetAuthTokenResult

‫Chrome 105 ואילך

מאפיינים

• grantedScopes

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

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

• token

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

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

InvalidTokenDetails

מאפיינים

• token

  מחרוזת

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

ProfileDetails

‫Chrome 84 ואילך

מאפיינים

• accountStatus

  ‫AccountStatus אופציונלי

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

ProfileUserInfo

מאפיינים

• אימייל

  מחרוזת

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

• id [מזהה]

  מחרוזת

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

TokenDetails

מאפיינים

• חשבון

  ‫AccountInfo אופציונלי

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

• enableGranularPermissions

  boolean אופציונלי

  ‫Chrome 87 ואילך

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

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

  boolean אופציונלי

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

• היקפים

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

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

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

WebAuthFlowDetails

מאפיינים

• abortOnLoadForNonInteractive

  boolean אופציונלי

  ‫Chrome 113 ואילך

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

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

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

  boolean אופציונלי

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

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

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

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

• timeoutMsForNonInteractive

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

  ‫Chrome 113 ואילך

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

• כתובת אתר

  מחרוזת

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

Methods

clearAllCachedAuthTokens()

‫Chrome 87 ואילך

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

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

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

החזרות

• Promise<void>

  ‫Chrome 106 ואילך

  מחזירה Promise שמושלם כשהמצב נוקה.

getAccounts()

ערוץ פיתוח

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

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

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

החזרות

• Promise<AccountInfo[]>

getAuthToken()

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

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

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

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

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

פרמטרים

• פרטים

  ‫TokenDetails אופציונלי

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

החזרות

• Promise<GetAuthTokenResult>

  ‫Chrome 105 ואילך

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

getProfileUserInfo()

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

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

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

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

פרמטרים

• פרטים

  ‫ProfileDetails אופציונלי

  ‫Chrome 84 ואילך

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

החזרות

• ‫Promise<ProfileUserInfo>

  ‫Chrome 106 ואילך

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

getRedirectURL()

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

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

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

פרמטרים

• נתיב

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

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

החזרות

• מחרוזת

launchWebAuthFlow()

chrome.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 ואילך

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

removeCachedAuthToken()

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

הפעולה הזו מסירה אסימון גישה מסוג OAuth2 ממטמון הטוקנים של Identity API.

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

פרמטרים

• פרטים

  InvalidTokenDetails

  פרטי הטוקן.

החזרות

• Promise<void>

  ‫Chrome 106 ואילך

  מחזירה הבטחה (Promise) שמושלמת כשהאסימון מוסר מהמטמון.

אירועים

onSignInChanged

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

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

פרמטרים

• callback

  פונקציה

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

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

  • חשבון

    AccountInfo

  • signedIn

    בוליאני