chrome.identity

תיאור

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

הרשאות

identity

סוגים

AccountInfo

תכונות

  • id

    מחרוזת

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

AccountStatus

Chrome 84 ומעלה

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

'סנכרון'
ההגדרה קובעת שהסנכרון מופעל בחשבון הראשי.

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

GetAuthTokenResult

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

תכונות

  • grantedScopes

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

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

  • אסימון

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

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

InvalidTokenDetails

תכונות

  • אסימון

    מחרוזת

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

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 קיים, הוא מבטל את רשימת ההיקפים שצוינה ב-manifest.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()

Promise Chrome 87 ואילך 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

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

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

פרמטרים

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 106 ומעלה

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

getAccounts()

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

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

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

פרמטרים

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

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

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

    (accounts: AccountInfo[])=>void

החזרות

  • Promise<AccountInfo[]>

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

getAuthToken()

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

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

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

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

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

פרמטרים

  • פרטים

    TokenDetails אופציונלי

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

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

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

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

    (result: GetAuthTokenResult)=>void

החזרות

  • Chrome מגרסה 105 ואילך

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

getProfileUserInfo()

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

אחזור של כתובת אימייל ומזהה gaia עם ערפול קוד (obfuscated) של המשתמש שמחובר לפרופיל.

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

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

פרמטרים

  • פרטים

    ProfileDetails (פרטי הפרופיל) אופציונלי

    Chrome 84 ומעלה

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

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

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

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

    (userInfo: ProfileUserInfo)=>void

החזרות

  • Promise<ProfileUserInfo>

    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

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

החזרות

  • הבטחה<string|undefined>

    Chrome 106 ומעלה

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

removeCachedAuthToken()

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

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

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

פרמטרים

  • פרטים

    InvalidTokenDetails

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

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 106 ומעלה

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

אירועים

onSignInChanged

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

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

פרמטרים

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

    פונקציה

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

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