תיאור
עליך להשתמש ב-API של chrome.identity
כדי לקבל אסימוני גישה מסוג OAuth2.
הרשאות
identity
סוגים
AccountInfo
תכונות
-
id
string
מזהה ייחודי של החשבון. המזהה הזה לא ישתנה בכל משך החיים של החשבון.
AccountStatus
טיפוסים בני מנייה (enum)
'סנכרון'
ההגדרה קובעת שהסנכרון מופעל בחשבון הראשי.
"ANY"
מציין את קיומו של חשבון ראשי, אם יש כזה.
GetAuthTokenResult
תכונות
-
grantedScopes
string[] אופציונלי
רשימה של היקפי הרשאות OAuth2 שהוענקו לתוסף.
-
token
מחרוזת אופציונלי
האסימון הספציפי שמשויך לבקשה.
InvalidTokenDetails
תכונות
-
token
string
האסימון הספציפי שיש להסיר מהמטמון.
ProfileDetails
תכונות
-
accountStatus
AccountStatus אופציונלי
סטטוס של החשבון הראשי שמחובר לפרופיל שצריך להחזיר לו
ProfileUserInfo
. ברירת המחדל היא סטטוס החשבוןSYNC
.
ProfileUserInfo
תכונות
-
אימייל
string
כתובת אימייל של חשבון המשתמש שמחובר לפרופיל הנוכחי. השדה ריק אם המשתמש לא מחובר לחשבון או אם לא צוינה הרשאת המניפסט
identity.email
. -
id
string
מזהה ייחודי של החשבון. המזהה הזה לא ישתנה בכל משך החיים של החשבון. השדה ריק אם המשתמש לא מחובר לחשבון או (בגרסה 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
. -
כתובת אתר
string
כתובת ה-URL שמתחילה את תהליך האימות.
שיטות
clearAllCachedAuthTokens()
chrome.identity.clearAllCachedAuthTokens(
callback?: function,
)
איפוס המצב של Identity API:
- הסרת כל אסימוני הגישה מסוג OAuth2 ממטמון האסימון
- הסרת ההעדפות בחשבון של המשתמש
- ביטול ההרשאה של המשתמש מכל תהליכי האימות
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
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.
ה-Identity API שומר אסימוני גישה בזיכרון, כך שמותר לקרוא ל-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 עם ערפול קוד (obfuscated) של המשתמש שמחובר לפרופיל.
נדרשת הרשאת המניפסט 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 שנוצרה.
החזרות
-
string
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 | undefined>
Chrome 106 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
removeCachedAuthToken()
chrome.identity.removeCachedAuthToken(
details: InvalidTokenDetails,
callback?: function,
)
הסרת אסימון גישה מסוג OAuth2 ממטמון האסימון של Identity API.
אם מתגלה שאסימון גישה לא חוקי, יש להעביר אותו אל removeCachedAuthToken כדי להסיר אותו מהמטמון. לאחר מכן האפליקציה יכולה לאחזר אסימון חדש באמצעות getAuthToken
.
פרמטרים
-
פרטים
פרטי האסימון.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 106 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
אירועים
onSignInChanged
chrome.identity.onSignInChanged.addListener(
callback: function,
)
מופעל כשמצב הכניסה לחשבון משתנה בפרופיל של המשתמש.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(account: AccountInfo, signedIn: boolean) => void
-
חשבון
-
signedIn
boolean
-