chrome.identity

תיאור

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

הרשאות

identity

סוגים

AccountInfo

מאפיינים

  • id [מזהה]

    מחרוזת

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

AccountStatus

Chrome 84 ואילך

Enum

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

"אחד או יותר"
מציין אם קיים חשבון ראשי.

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

    ערך בוליאני אופציונלי

    Chrome מגרסה 87 ואילך

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

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

    ערך בוליאני אופציונלי

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

  • היקפים

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

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

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

WebAuthFlowDetails

מאפיינים

  • abortOnLoadForNonInteractive

    ערך בוליאני אופציונלי

    Chrome 113 ואילך

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

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

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

    ערך בוליאני אופציונלי

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

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

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

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

  • timeoutMsForNonInteractive

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

    Chrome 113 ואילך

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

  • כתובת אתר

    מחרוזת

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

שיטות

clearAllCachedAuthTokens()

הבטחה Chrome מגרסה 87 ואילך 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 106+

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

getAccounts()

הבטחה ערוץ פיתוח 
chrome.identity.getAccounts(
  callback?: function,
)

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (accounts: AccountInfo[]) => void

החזרות

  • Promise&lt;AccountInfo[]&gt;

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

getAuthToken()

הבטחה 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

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

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

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

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

פרמטרים

  • פרטים

    TokenDetails אופציונלי

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (result: GetAuthTokenResult) => void

החזרות

  • Promise&lt;GetAuthTokenResult&gt;

    Chrome 105+

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

getProfileUserInfo()

הבטחה 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

אחזור כתובת אימייל ומזהה GAIA של משתמש שמחובר לפרופיל, לאחר ערפול קוד (obfuscation).

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

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

פרמטרים

  • פרטים

    ProfileDetails אופציונלי

    Chrome 84 ואילך

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (userInfo: ProfileUserInfo) => void

החזרות

  • Promise&lt;ProfileUserInfo&gt;

    Chrome 106+

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

getRedirectURL()

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

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

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

פרמטרים

  • נתיב

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

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

החזרות

  • מחרוזת

launchWebAuthFlow()

הבטחה 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
)

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

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

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

פרמטרים

  • פרטים

    WebAuthFlowDetails

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    (responseUrl?: string) => void

    • responseUrl

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

החזרות

  • Promise<string | לא מוגדר>

    Chrome 106+

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

removeCachedAuthToken()

הבטחה 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
)

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

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

פרמטרים

  • פרטים

    InvalidTokenDetails

    פרטי האסימון.

  • קריאה חוזרת (callback)

    פונקציה אופציונלית

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 106+

    הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.

אירועים

onSignInChanged

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

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

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