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. המדיניות הזו תקפה רק אם המדיניות interactive מוגדרת כ-false.

  • כתובת אתר

    מחרוזת

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

Methods

clearAllCachedAuthTokens()

‫Chrome 87 ואילך 
chrome.identity.clearAllCachedAuthTokens(): Promise<void>

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

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

החזרות

  • Promise<void>

    ‫Chrome 106 ואילך

getAccounts()

ערוץ פיתוח 
chrome.identity.getAccounts(): Promise<AccountInfo[]>

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

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

החזרות

getAuthToken()

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

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

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

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

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

פרמטרים

  • פרטים

    ‫TokenDetails אופציונלי

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

החזרות

getProfileUserInfo()

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

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

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

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

פרמטרים

  • פרטים

    ‫ProfileDetails אופציונלי

    ‫Chrome 84 ואילך

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

החזרות

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.

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

פרמטרים

החזרות

  • Promise<string | undefined>

    ‫Chrome 106 ואילך

removeCachedAuthToken()

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

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

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 106 ואילך

אירועים

onSignInChanged

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

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

פרמטרים

  • callback

    פונקציה

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

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