תיאור
משתמשים ב-API chrome.identity
כדי לקבל אסימוני גישה מסוג OAuth2.
הרשאות
identity
סוגים
AccountInfo
מאפיינים
-
id [מזהה]
מחרוזת
מזהה ייחודי של החשבון. המזהה הזה לא ישתנה בכל משך החיים של החשבון.
AccountStatus
Enum
'סנכרון'
מציין שהסנכרון מופעל עבור החשבון הראשי.
"אחד או יותר"
מציין אם קיים חשבון ראשי.
GetAuthTokenResult
מאפיינים
-
grantedScopes
string[] אופציונלי
רשימה של היקפי הרשאות OAuth2 שהוענקו לתוסף.
-
token
מחרוזת אופציונלי
האסימון הספציפי שמשויך לבקשה.
InvalidTokenDetails
מאפיינים
-
token
מחרוזת
האסימון הספציפי שצריך להסיר מהמטמון.
ProfileDetails
מאפיינים
-
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.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<AccountInfo[]>
הבטחות נתמכות במניפסט מגרסה 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
-
תוצאהChrome 105+
-
החזרות
-
Promise<GetAuthTokenResult>
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
-
userInfo
-
החזרות
-
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
.
כדי שחוויית המשתמש תהיה חיובית, חשוב לבצע את תהליכי האימות האינטראקטיביים על ידי ממשק המשתמש באפליקציה כדי להסביר למה מיועדת ההרשאה. אם לא תעשו זאת, המשתמשים יקבלו בקשות הרשאה ללא הקשר. בפרט, אין להפעיל תהליך אימות אינטראקטיבי כאשר האפליקציה מופעלת לראשונה.
פרמטרים
-
פרטים
אפשרויות לתהליך 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
.
פרמטרים
-
פרטים
פרטי האסימון.
-
קריאה חוזרת (callback)
פונקציה אופציונלית
הפרמטר
callback
נראה כך:() => void
החזרות
-
הבטחה<Empty>
Chrome 106+הבטחות נתמכות במניפסט מגרסה V3 ואילך, אבל ניתנות קריאות חוזרות (callback) בשביל תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה הזו מצליחה לפתור את הבעיה באותו סוג שמועבר לקריאה החוזרת.
אירועים
onSignInChanged
chrome.identity.onSignInChanged.addListener(
callback: function,
)
מופעל כשמצב הכניסה לחשבון משתנה בפרופיל של המשתמש.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(account: AccountInfo, signedIn: boolean) => void
-
חשבון
-
signedIn
בוליאני
-