בדף העזר הזה מתואר ה-JavaScript API של "כניסה באמצעות חשבון Google", שמשמש להצגת הלחצן "כניסה באמצעות חשבון Google" או ההודעה "כניסה בנגיעה אחת" בדפי אינטרנט.
השיטה: google.accounts.id.initialize
השיטה google.accounts.id.initialize מאתחלת את הלקוח של "כניסה באמצעות חשבון Google" על סמך אובייקט ההגדרה. דוגמת הקוד הבאה ממחישה את השיטה:
google.accounts.id.initialize(IdConfiguration)
בדוגמת הקוד הבאה מוטמעת השיטה google.accounts.id.initialize עם פונקציית onload:
<script>
window.onload = function () {
google.accounts.id.initialize({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: handleCredentialResponse
});
google.accounts.id.prompt();
};
</script>
ה-method google.accounts.id.initialize יוצרת מופע של לקוח "כניסה באמצעות חשבון Google" שכל המודולים באותו דף אינטרנט יכולים להשתמש בו באופן משתמע.
- צריך לקרוא ל-method
google.accounts.id.initializeרק פעם אחת, גם אם משתמשים בכמה מודולים (כמו One Tap, לחצן בהתאמה אישית, ביטול וכו') באותו דף אינטרנט. - אם קוראים ל-method
google.accounts.id.initializeכמה פעמים, רק ההגדרות מהקריאה האחרונה נשמרות ומשמשות את המערכת.
למעשה, אתם מאפסים את ההגדרות בכל פעם שאתם קוראים ל-method google.accounts.id.initialize, וכל ה-methods הבאות באותו דף אינטרנט משתמשות מיד בהגדרות החדשות.
סוג הנתונים: IdConfiguration
בטבלה הבאה מפורטים השדות והתיאורים של סוג הנתונים IdConfiguration:
| שדה | |
|---|---|
client_id |
מזהה הלקוח של האפליקציה |
color_scheme |
ערכת הצבעים שמוחלת על ההודעה של One Tap. |
auto_select |
הפעלת בחירה אוטומטית. |
callback |
פונקציית ה-JavaScript שמטפלת בטוקנים של מזהים. המאפיין הזה משמש את מנגנון "לחיצה אחת" של Google ואת מצב חוויית המשתמש של הכפתור popup "כניסה באמצעות חשבון Google". |
login_uri |
כתובת ה-URL של נקודת הקצה לכניסה. הכפתור "כניסה באמצעות חשבון Google"
redirect במצב UX משתמש במאפיין הזה. |
native_callback |
פונקציית ה-JavaScript שמטפלת בפרטי הכניסה של הסיסמה. |
cancel_on_tap_outside |
מבטלת את ההודעה אם המשתמש לוחץ מחוץ להודעה. |
prompt_parent_id |
מזהה ה-DOM של רכיב המאגר של ההודעה לאימות בלחיצה אחת |
nonce |
מחרוזת אקראית לטוקנים של מזהים |
essential_claims |
הצהרות נוספות שצריך לכלול בטוקן של המזהה ש-Google מחזירה. |
context |
הכותרת והמילים בהודעה של "כניסה בנגיעה אחת" |
state_cookie_domain |
אם צריך להפעיל את One Tap בדומיין הראשי ובתת-הדומיינים שלו, צריך להעביר את הדומיין הראשי לשדה הזה כדי להשתמש בקובץ Cookie משותף אחד. |
ux_mode |
תהליך חוויית המשתמש של הכפתור "כניסה באמצעות חשבון Google" |
allowed_parent_origin |
המקורות שמורשים להטמיע את ה-iframe המתווך. אם השדה הזה קיים, One Tap פועל במצב iframe ביניים. |
intermediate_iframe_close_callback |
מבטלת את התנהגות ברירת המחדל של iframe הביניים כשמשתמשים סוגרים ידנית את One Tap. |
itp_support |
הפעלת חוויית משתמש משודרגת של One Tap בדפדפנים עם ITP. |
login_hint |
דילוג על בחירת החשבון על ידי מתן רמז למשתמש. |
hd |
הגבלת בחירת החשבון לפי דומיין. |
use_fedcm_for_prompt |
מאפשרים לדפדפן לשלוט בהצעות למשתמשים להיכנס לחשבון ולתווך בתהליך הכניסה לחשבון בין האתר שלכם לבין Google. |
use_fedcm_for_button |
השדה הזה קובע אם להשתמש בממשק המשתמש של FedCM עם כפתור ב-Chrome (גרסה M125 ואילך במחשב וגרסה M128 ואילך ב-Android). ערך ברירת המחדל הוא false. |
button_auto_select |
אם להפעיל את האפשרות בחירה אוטומטית בתהליך של FedCM באמצעות כפתור. אם האפשרות הזו מופעלת, משתמשים חוזרים עם סשן פעיל ב-Google יתחברו באופן אוטומטי, בלי לעבור דרך ההודעה של Account Chooser.ערך ברירת המחדל הוא false. |
client_id
השדה הזה הוא מזהה הלקוח של האפליקציה, שנוצר ונמצא במסוף Google Cloud. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | כן | client_id: "CLIENT_ID.apps.googleusercontent.com" |
color_scheme
השדה הזה הוא ערכת הצבעים שמוחלת על ההודעה של One Tap. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | זה שינוי אופציונלי. כברירת מחדל, ערכת הצבעים של המערכת של המשתמשים. | color_scheme: "dark" |
בטבלה הבאה מפורטות ערכות הצבעים הזמינות והתיאורים שלהן.
| ערכת צבעים | |
|---|---|
default |
החלת ערכת הצבעים שמוגדרת כברירת מחדל במערכת של המשתמש, בהתאם להעדפה של המשתמש (ערכת צבעים בהירה או כהה). |
light |
החלת ערכת צבעים בהירה. |
dark |
להחיל ערכת צבעים כהה. |
auto_select
השדה הזה קובע אם טוקן של מזהה יוחזר באופן אוטומטי בלי אינטראקציה של המשתמש, כשיש רק סשן אחד ב-Google שאישר את האפליקציה שלכם בעבר. ערך ברירת המחדל הוא false. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| בוליאני | אופציונלי | auto_select: true |
callback
השדה הזה הוא פונקציית JavaScript שמטפלת בטוקן של המזהה שמוחזר מההודעה של One Tap או מהחלון הקופץ. המאפיין הזה נדרש אם משתמשים במנגנון "לחיצה אחת" של Google או במצב חוויית המשתמש popup של הכפתור "כניסה באמצעות חשבון Google". מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| פונקציה | נדרש לאימות בלחיצה אחת ולמצב חוויית המשתמש popup |
callback: handleResponse |
login_uri
המאפיין הזה הוא ה-URI של נקודת הקצה להתחברות.
הערך חייב להתאים בדיוק לאחד מכתובות ה-URI המורשות להפניה אוטומטית של לקוח OAuth 2.0, שהגדרתם במסוף Google Cloud, והוא חייב לעמוד בכללי האימות של כתובות URI להפניה אוטומטית.
אפשר להשמיט את המאפיין הזה אם הדף הנוכחי הוא דף ההתחברות. במקרה כזה, פרטי הכניסה נשלחים לדף הזה כברירת מחדל.
התגובה של פרטי הכניסה של טוקן המזהה מתפרסמת בנקודת הקצה (endpoint) של ההתחברות כשמשתמש לוחץ על הכפתור "כניסה באמצעות חשבון Google" ונעשה שימוש במצב UX של הפניה אוטומטית.
מידע נוסף מופיע בטבלה הבאה:
| סוג | אופציונלי | דוגמה |
|---|---|---|
| כתובת URL | ברירת המחדל היא ה-URI של הדף הנוכחי, או הערך שאתם מציינים. בשימוש רק כשמוגדר ux_mode: "redirect". |
login_uri: "https://www.example.com/login" |
נקודת הקצה (endpoint) של ההתחברות צריכה לטפל בבקשות POST שמכילות פרמטר credential עם ערך של טוקן מזהה בגוף הבקשה. השדה select_by לא נכלל בבקשות HTTP POST אל login_uri או data-login_uri, והוא מוחזר רק באובייקט CredentialResponse שמועבר לפונקציית JavaScript callback.
native_callback
השדה הזה הוא השם של פונקציית ה-JavaScript שמטפלת בפרטי הכניסה של הסיסמה שמוחזרים מ-Credential Manager המובנה של הדפדפן. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| פונקציה | אופציונלי | native_callback: handleResponse |
cancel_on_tap_outside
השדה הזה קובע אם לבטל את הבקשה של One Tap אם המשתמש לוחץ מחוץ להודעה. ערך ברירת המחדל הוא true. כדי להשבית את התכונה, צריך להגדיר את הערך ל-false. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| בוליאני | אופציונלי | cancel_on_tap_outside: false |
prompt_parent_id
המאפיין הזה מגדיר את מזהה ה-DOM של רכיב מאגר התגים. אם המדיניות לא מוגדרת, ההודעה של One Tap מוצגת בפינה השמאלית העליונה של החלון. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | prompt_parent_id: 'parent_id' |
צופן חד-פעמי (nonce)
השדה הזה הוא מחרוזת אקראית שמשמשת את הטוקן של המזהה כדי למנוע התקפות שליחה מחדש. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | nonce: "biaqbm70g23" |
אורך ה-nonce מוגבל לגודל המקסימלי של JWT שנתמך בסביבה שלכם, ולמגבלות הגודל של HTTP בדפדפן ובשרת הספציפיים.
essential_claims
השדה הזה הוא מחרוזת שמשמשת לבקשת הצהרות נוספות שייכללו בטוקן של מזהה ש-Google מחזירה. כאן מופיעה רשימה מלאה של ההצהרות ש-Google מקבלת.
מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | essential_claims: "auth_time, amr" |
הקשר
השדה הזה משנה את הטקסט של הכותרת וההודעות שמוצגות בהודעה של One Tap, ואין לו השפעה על דפדפני ITP. ברירת המחדל היא signin.
מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | context: "use" |
בטבלה הבאה מפורטים כל ההקשרים הזמינים והתיאורים שלהם:
| הקשר | |
|---|---|
signin |
"כניסה אל" |
signup |
"הרשמה אל" |
use |
"שימוש" |
state_cookie_domain
אם אתם צריכים להציג את מנגנון "לחיצה אחת" בדומיין הראשי ובתת-הדומיינים שלו, העבירו את הדומיין הראשי לשדה הזה כדי להשתמש בקובץ Cookie אחד במצב משותף. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | state_cookie_domain: "example.com" |
ux_mode
בשדה הזה מגדירים את תהליך חוויית המשתמש של הכפתור "כניסה באמצעות חשבון Google". ערך ברירת המחדל הוא popup. למאפיין הזה אין השפעה על חוויית המשתמש של OneTap. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | ux_mode: "redirect" |
בטבלה הבאה מפורטים מצבי חוויית המשתמש הזמינים והתיאורים שלהם.
| מצב UX | |
|---|---|
popup |
מבצע את תהליך הכניסה לחשבון בחלון קופץ. |
redirect |
מבצע את תהליך הכניסה של חוויית המשתמש באמצעות הפניה אוטומטית לדף מלא. |
allowed_parent_origin
המקורות שמורשים להטמיע את ה-iframe המתווך. אם השדה הזה קיים, One Tap פועל במצב iframe ביניים. מידע נוסף מפורט בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת או מערך מחרוזות | אופציונלי | allowed_parent_origin: "https://example.com" |
בטבלה הבאה מפורטים סוגי הערכים הנתמכים והתיאורים שלהם.
| סוגי ערכים | ||
|---|---|---|
string |
URI של דומיין אחד. | "https://example.com" |
string array |
מערך של כתובות URI של דומיינים. | ["https://news.example.com", "https://local.example.com"] |
יש גם תמיכה בקידומות של תווים כלליים לחיפוש. לדוגמה, "https://*.example.com" תואם ל-example.com ולתת-הדומיינים שלו בכל הרמות (למשל news.example.com, login.news.example.com). דברים שחשוב לזכור כשמשתמשים בתווים כלליים לחיפוש:
- מחרוזות של תבניות לא יכולות להיות מורכבות רק מתו כללי לחיפוש ומדומיין ברמה עליונה. לדוגמה,
https://.comו-https://.co.ukלא תקינים כי"https://.example.com"תואם ל-example.comולכל תתי-הדומיינים שלו. כדי לייצג שני דומיינים שונים, צריך להשתמש ברשימה מופרדת בפסיקים. לדוגמה,"https://example1.com,https://.example2.com"תואם לדומייניםexample1.com,example2.comולתת-הדומיינים שלexample2.com - דומיינים עם תו כללי לחיפוש חייבים להתחיל בסכימת https:// מאובטחת, ולכן
"*.example.com"נחשב לא חוקי.
אם הערך של השדה allowed_parent_origin לא תקין, ההפעלה של One Tap במצב iframe ביניים תיכשל ותיפסק.
intermediate_iframe_close_callback
מבטלת את התנהגות ברירת המחדל של iframe הביניים כשמשתמשים סוגרים ידנית את One Tap על ידי לחיצה על הלחצן "X" בממשק המשתמש של One Tap. פעולת ברירת המחדל היא להסיר את ה-iframe המתווך מה-DOM באופן מיידי.
השדה intermediate_iframe_close_callback משפיע רק במצב iframe ביניים. והיא משפיעה רק על ה-iframe של הביניים, ולא על ה-iframe של One Tap. ממשק המשתמש של One Tap מוסר לפני שהקריאה החוזרת (callback) מופעלת.
| סוג | חובה | דוגמה |
|---|---|---|
| פונקציה | אופציונלי | intermediate_iframe_close_callback: logBeforeClose |
itp_support
השדה הזה קובע אם חוויית המשתמש המשודרגת של One Tap תופעל בדפדפנים שתומכים במניעת מעקב חכמה (ITP). ערך ברירת המחדל הוא false. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| בוליאני | אופציונלי | itp_support: false |
login_hint
אם האפליקציה יודעת מראש איזה משתמש צריך להיכנס, היא יכולה לספק רמז להתחברות ל-Google. אם התהליך מצליח, המערכת מדלגת על בחירת החשבון. הערכים הקבילים הם: כתובת אימייל או ערך של שדה sub בטוקן של מזהה.
למידע נוסף, קראו על השדה login_hint במסמכי התיעוד של OpenID Connect.
| סוג | חובה | דוגמה |
|---|---|---|
מחרוזת, כתובת אימייל או הערך משדה sub של טוקן מזהה. |
אופציונלי | login_hint: 'elisa.beckett@gmail.com' |
hd
אם למשתמש יש כמה חשבונות והוא צריך להיכנס רק באמצעות חשבון Workspace, אפשר להשתמש בהגדרה הזו כדי לספק ל-Google רמז לשם הדומיין. אם הפעולה מצליחה, חשבונות המשתמשים שמוצגים במהלך בחירת החשבון מוגבלים לדומיין שצוין.
ערך של תו כללי לחיפוש: * מציע למשתמש רק חשבונות Workspace ולא כולל חשבונות פרטיים (user@gmail.com) במהלך בחירת החשבון.
מידע נוסף זמין בשדה hd במסמכי התיעוד של OpenID Connect.
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת. שם דומיין שמוגדר במלואו או *. | אופציונלי | hd: '*' |
use_fedcm_for_prompt
מאפשרים לדפדפן לשלוט בהצעות למשתמשים להיכנס לחשבון ולתווך בתהליך הכניסה לחשבון בין האתר שלכם לבין Google. ערך ברירת המחדל הוא false. מידע נוסף זמין בדף מעבר ל-FedCM.
| סוג | חובה | דוגמה |
|---|---|---|
| בוליאני | הוצא משימוש | use_fedcm_for_prompt: true |
use_fedcm_for_button
השדה הזה קובע אם להשתמש בחוויית המשתמש של FedCM עם כפתור ב-Chrome (גרסה M125 ואילך במחשב וגרסה M128 ואילך ב-Android). ערך ברירת המחדל הוא false. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| בוליאני | אופציונלי | use_fedcm_for_button: true |
button_auto_select
השדה הזה קובע אם להפעיל את האפשרות בחירה אוטומטית בתהליך של FedCM באמצעות כפתור. אם המדיניות מופעלת, משתמשים חוזרים עם סשן פעיל ב-Google יתחברו באופן אוטומטי, בלי לעבור דרך ההנחיה של Account Chooser. ערך ברירת המחדל הוא false. צריך להפעיל באופן מפורש את הכניסה האוטומטית באמצעות כפתור במהלך ההשקה של ההצטרפות. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| בוליאני | אופציונלי | button_auto_select: true |
Method: google.accounts.id.prompt
ה-method google.accounts.id.prompt מציגה את ההודעה של One Tap או את Credential Manager המובנה בדפדפן אחרי שמפעילים את ה-method initialize().
דוגמה לקוד של השיטה:
google.accounts.id.prompt(/**
@type{(function(!PromptMomentNotification):void)=} */ momentListener)
בדרך כלל, השיטה prompt() מופעלת כשהדף נטען. בגלל סטטוס הסשן והגדרות המשתמש בצד של Google, יכול להיות שממשק המשתמש של ההודעה בלחיצה אחת לא יוצג. כדי לקבל התראות על סטטוס ממשק המשתמש ברגעים שונים, צריך להעביר פונקציה לקבלת התראות על סטטוס ממשק המשתמש.
ההתראות מופעלות ברגעים הבאים:
- רגע ההצגה: זה קורה אחרי שמתבצעת קריאה ל-method
prompt(). ההתראה מכילה ערך בוליאני שמציין אם ממשק המשתמש מוצג או לא. רגע שדילגו עליו: זה קורה כשההודעה של One Tap נסגרת בגלל ביטול אוטומטי, ביטול ידני או כש-Google לא מצליחה להנפיק פרטי כניסה, למשל כשהסשן שנבחר יצא מהחשבון ב-Google.
במקרים כאלה, מומלץ להמשיך לספקי הזהויות הבאים, אם יש כאלה.
רגע הסגירה: הרגע הזה מתרחש כש-Google מאחזרת את פרטי הכניסה או כשהמשתמש רוצה להפסיק את תהליך האחזור של פרטי הכניסה. לדוגמה, כשהמשתמש מתחיל להזין את שם המשתמש והסיסמה שלו בתיבת הדו-שיח של ההתחברות, אתם יכולים להפעיל את השיטה
google.accounts.id.cancel()כדי לסגור את ההודעה של One Tap ולהפעיל רגע של סגירה.
דוגמת הקוד הבאה מטמיעה את הרגע שדילגו עליו:
<script>
window.onload = function () {
google.accounts.id.initialize(...);
google.accounts.id.prompt((notification) => {
if (notification.isNotDisplayed() || notification.isSkippedMoment()) {
// continue with another identity provider.
}
});
};
</script>
סוג הנתונים: PromptMomentNotification
בטבלה הבאה מפורטות השיטות והתיאורים של סוג הנתונים PromptMomentNotification:
| שיטה | |
|---|---|
isDisplayMoment() |
הפונקציה מחזירה true אם ההודעה של One Tap מוצגת.הערה: כשהתכונה FedCM מופעלת, ההתראה הזו לא נתמכת. מידע נוסף זמין בדף מעבר ל-FedCM. |
isDisplayed() |
הפונקציה מחזירה את הערך true אם סוג הרגע הוא PromptMoment.DISPLAY וההודעה "בלחיצה אחת" מוצגת.הערה: כשהתכונה FedCM מופעלת, ההתראה הזו לא נתמכת. מידע נוסף זמין בדף מעבר ל-FedCM. |
isNotDisplayed() |
הפונקציה מחזירה את הערך true אם סוג הרגע הוא PromptMoment.DISPLAY וההודעה "כניסה בנגיעה אחת" לא מוצגת.הערה: כשהתכונה FedCM מופעלת, ההתראה הזו לא נתמכת. מידע נוסף זמין בדף מעבר ל-FedCM. |
getNotDisplayedReason() |
הסיבה המפורטת לכך שממשק המשתמש לא מוצג. אלה הערכים האפשריים:
|
isSkippedMoment() |
החזרותtrue אם סוג הרגע הואPromptMoment.SKIPPEDפֶּתֶק: כאשר FedCM מופעל, שיטה זו נתמכת באופן חלקי. באופן ספציפי, אין תמיכה בסיבה לדילוג user_cancel. מידע נוסף זמין בדף מעבר ל-FedCM.
|
getSkippedReason() |
הסיבה המפורטת לדילוג על הרגע. אלה הערכים האפשריים:
user_cancel. מידע נוסף זמין בדף מעבר ל-FedCM.
|
isDismissedMoment() |
הפונקציה מחזירה את הערך true אם סוג הרגע הוא
PromptMoment.DISMISSED.הערה: כש-FedCM מופעל, השיטה הזו נתמכת באופן מלא. מידע נוסף זמין בדף מעבר ל-FedCM. |
getDismissedReason() |
הסיבה המפורטת לדחייה. אלה הערכים האפשריים:
|
getMomentType() |
מחזירה מחרוזת של סוג הרגע. אלה הערכים האפשריים:
|
סוג הנתונים: CredentialResponse
כשפונקציית callback מופעלת, אובייקט CredentialResponse מועבר כפרמטר. בטבלה הבאה מפורטים השדות שכלולים באובייקט התגובה של פרטי הכניסה:
| שדה | |
|---|---|
credential |
הטוקן המקודד של מזהה ה-JWT ש-Google מנפיקה. |
select_by |
איך המשתמש נכנס לחשבון. |
state |
השדה הזה מוגדר רק כשהמשתמש לוחץ על כפתור "כניסה באמצעות חשבון Google" כדי להיכנס, ומוגדר המאפיין state של הכפתור. |
מסמך לאימות
השדה הזה הוא טוקן של מזהה כמחרוזת של טוקן אינטרנט מסוג JSON (JWT) בקידוד Base64.
אחרי פענוח, ה-JWT נראה כמו בדוגמה הבאה:
header { "alg": "RS256", "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature "typ": "JWT" } payload { "iss": "https://accounts.google.com", // The JWT's issuer "nbf": 161803398874, "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID "sub": "3141592653589793238", // The unique ID of the user's Google Account "hd": "gmail.com", // If present, the host domain of the user's Google Workspace email address "auth_time": 1748875426, "amr": ["mfa", "pwd", "tel"], "email": "elisa.g.beckett@gmail.com", // The user's email address "email_verified": true, // true, if Google has verified the email address "azp": "314159265-pi.apps.googleusercontent.com", "name": "Elisa Beckett", // If present, a URL to user's profile picture "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler", "given_name": "Elisa", "family_name": "Beckett", "iat": 1596474000, // Unix timestamp of the assertion creation time "exp": 1596477600, // Unix timestamp of the assertion expiration time "jti": "abc161803398874def" }
השדה sub הוא מזהה ייחודי גלובלי של חשבון Google. רק השדה sub משמש כמזהה של המשתמש, כי הוא ייחודי לכל חשבונות Google ואי אפשר להשתמש בו שוב.
בעזרת השדות email, email_verified ו-hd אתם יכולים לקבוע אם Google מארחת כתובת אימייל מסוימת והיא המקור המהימן שלה. במקרים שבהם Google היא הסמכות, המשתמש מאומת כבעלים החוקי של החשבון.
מקרים שבהם Google היא הסמכות:
-
emailעם הסיומת@gmail.comהוא חשבון Gmail. -
email_verifiedהוא true ומוגדרhd, זהו חשבון Google Workspace.
משתמשים יכולים להירשם לחשבונות Google בלי להשתמש ב-Gmail או ב-Google Workspace.
אם email לא מכיל סיומת @gmail.com ו-hd לא קיים, Google לא נחשבת כסמכותית ומומלץ להשתמש בסיסמה או בשיטות אימות אחרות כדי לאמת את המשתמש. גם email_verfied יכול להיות נכון, כי Google אימתה את המשתמש כשיצר את חשבון Google, אבל יכול להיות שהבעלות על החשבון אצל הצד השלישי השתנתה מאז.
בשדה exp מוצג מועד התפוגה של אימות האסימון בצד השרת. התוקף של טוקן המזהה שמתקבל מ"כניסה באמצעות חשבון Google" הוא שעה אחת. צריך לאמת את הטוקן לפני מועד התפוגה. אל תשתמשו ב-exp לניהול סשנים. אם פג התוקף של טוקן של מזהה, זה לא אומר שהמשתמש יצא מהחשבון. האפליקציה שלכם אחראית לניהול הסשנים של המשתמשים.
select_by
בטבלה הבאה מפורטים הערכים האפשריים של השדה select_by. סוג הכפתור שבו משתמשים, יחד עם הסשן ומצב ההסכמה, משמשים להגדרת הערך,
המשתמש לחץ על הכפתור One Tap או על הכפתור "כניסה באמצעות חשבון Google", או השתמש בתהליך הכניסה האוטומטית ללא מגע.
נמצא סשן קיים, או שהמשתמש בחר חשבון Google ונכנס אליו כדי ליצור סשן חדש.
לפני שיתוף פרטי הכניסה של טוקן המזהה עם האפליקציה, המשתמש:
- לחצו על הכפתור "אישור" כדי להביע הסכמה לשיתוף פרטי הכניסה, או
- כבר נתנו הסכמה והשתמשו באפשרות "בחירת חשבון" כדי לבחור חשבון Google.
הערך של השדה הזה מוגדר לאחד מהסוגים הבאים:
| ערך | תיאור |
|---|---|
auto |
כניסה אוטומטית של משתמש עם סשן קיים שכבר נתן הסכמה לשיתוף פרטי הכניסה. רלוונטי רק לדפדפנים שלא תומכים ב-FedCM. |
user |
משתמש עם סשן קיים שכבר נתן הסכמה בעבר לחץ על הכפתור "המשך בתור" באימות בלחיצה אחת כדי לשתף את פרטי הכניסה. ההגדרה רלוונטית רק לדפדפנים שלא תומכים ב-FedCM. |
fedcm |
המשתמש לחץ על הכפתור "המשך בתור" באימות בלחיצה אחת כדי לשתף את פרטי הכניסה באמצעות FedCM. ההגדרה חלה רק על דפדפנים שתומכים ב-FedCM. |
fedcm_auto |
כניסה אוטומטית של משתמש עם סשן קיים שכבר נתן בעבר הסכמה לשיתוף פרטי הכניסה באמצעות FedCM One Tap. ההגדרה רלוונטית רק לדפדפנים שתומכים ב-FedCM. |
user_1tap |
משתמש עם סשן קיים לחץ על הכפתור "המשך בתור" באימות בלחיצה אחת כדי להביע הסכמה ולשתף את פרטי הכניסה. רלוונטי רק ל-Chrome מגרסה 75 ואילך. |
user_2tap |
משתמש בלי סשן קיים לחץ על הכפתור "המשך בתור" באימות בלחיצה אחת כדי לבחור חשבון, ואז לחץ על הכפתור "אישור" בחלון קופץ כדי להביע הסכמה ולשתף את פרטי הכניסה. ההגדרה חלה על דפדפנים שלא מבוססים על Chromium. |
itp |
משתמש שכבר נתן הסכמה בעבר לחץ על One Tap בדפדפני ITP. |
itp_confirm |
משתמש שלא נתן הסכמה לחץ על One Tap בדפדפני ITP, ואז לחץ על הכפתור "המשך" כדי לתת הסכמה ולשתף את פרטי הכניסה. |
btn |
משתמש שכבר נתן הסכמה בעבר לחץ על הכפתור "כניסה באמצעות חשבון Google" ובחר חשבון Google מתוך "בחירת חשבון" כדי לשתף את פרטי הכניסה. |
btn_confirm |
משתמש שלא נתן הסכמה לחץ על הכפתור "כניסה באמצעות חשבון Google" ואז על הכפתור "המשך" כדי לתת הסכמה ולשתף את פרטי הכניסה. |
מדינה (State)
השדה הזה מוגדר רק כשמשתמש לוחץ על כפתור "כניסה באמצעות חשבון Google" כדי להיכנס, והמאפיין state של הכפתור שנלחץ צוין. הערך של השדה הזה זהה לערך שציינתם במאפיין state של הכפתור.
אפשר להציג כמה כפתורי "כניסה באמצעות חשבון Google" באותו דף, ולכן אתם יכולים להקצות לכל כפתור מחרוזת ייחודית. לכן, אפשר להשתמש בשדה state הזה כדי לזהות על איזה כפתור המשתמש לחץ כדי להיכנס.
שיטה: google.accounts.id.renderButton
ה-method google.accounts.id.renderButton מציגה את הכפתור "כניסה באמצעות חשבון Google" בדפי האינטרנט שלכם.
דוגמה לקוד של השיטה:
google.accounts.id.renderButton(
/** @type{!HTMLElement} */ parent,
/** @type{!GsiButtonConfiguration} */ options
)
סוג הנתונים: GsiButtonConfiguration
בטבלה הבאה מפורטים השדות והתיאורים של סוג הנתונים GsiButtonConfiguration:
| מאפיין | |
|---|---|
type |
סוג הכפתור: סמל או כפתור רגיל. |
theme |
עיצוב הכפתור. לדוגמה, filled_blue או filled_black. |
size |
גודל הכפתור. לדוגמה, קטן או גדול. |
text |
הטקסט של הכפתור. לדוגמה, "כניסה באמצעות חשבון Google" או "הרשמה באמצעות חשבון Google". |
shape |
צורת הכפתור. לדוגמה, מלבני או עגול. |
logo_alignment |
יישור הלוגו של Google: לשמאל או למרכז. |
width |
רוחב הכפתור בפיקסלים. |
locale |
אם מגדירים את השפה, הכפתור מוצג בשפה הזו. |
click_listener |
אם מגדירים את הפונקציה הזו, המערכת קוראת לה כשלוחצים על הכפתור "כניסה באמצעות חשבון Google". |
state |
אם מגדירים את המחרוזת הזו, היא מוחזרת עם הטוקן של המזהה. |
סוגי מאפיינים
בקטעים הבאים מפורטים סוגי המאפיינים ודוגמה לכל אחד מהם.
סוג
סוג הכפתור. ערך ברירת המחדל הוא standard.
מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | כן | type: "icon" |
בטבלה הבאה מפורטים סוגי הלחצנים הזמינים והתיאורים שלהם:
| סוג | |
|---|---|
standard |
|
icon |
|
עיצוב
עיצוב הכפתור. ערך ברירת המחדל הוא outline. בטבלה הבאה מפורט מידע נוסף:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | theme: "filled_blue" |
בטבלה הבאה מפורטים העיצובים הזמינים והתיאורים שלהם:
| עיצוב | דוגמאות | מפרטים |
|---|---|---|
outline |
|
מילוי: #FFFFFF קו מתאר: #747775 | 1px | inside גופן: #1F1F1F | Roboto Medium | 14/20 בהתאמה אישית: #1F1F1F | Roboto | Medium 12/14 | Regular 11/13 |
filled_blue |
|
מילוי: #0B57D0 קו: #OB57D0 | 1px | inside גופן: #FFFFFF | Google Sans Medium | 14/20 בהתאמה אישית: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13 |
filled_black |
|
מילוי: #202124 קו מתאר: #OB57D0 | 1px | inside גופן: #FFFFFF | Google Sans Medium | 14/20 בהתאמה אישית: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13 |
outline_dark |
|
מילוי: #131314 קו: #8E918F | 1px | פנימי גופן: #FFFFFF | Google Sans Medium | 14/20 מותאם אישית: #FFFFFF | Roboto | Medium 12/14 | Regular 11/13 |
size
גודל הכפתור. ערך ברירת המחדל הוא large. בטבלה הבאה מפורט מידע נוסף:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | size: "small" |
בטבלה הבאה מפורטים הגדלים הזמינים של הכפתורים והתיאורים שלהם:
| גודל | |
|---|---|
large |
|
medium |
|
small |
|
text
הטקסט של הכפתור. ערך ברירת המחדל הוא signin_with. אין הבדלים חזותיים בטקסט של כפתורי סמלים שיש להם מאפייני text שונים.
החריג היחיד הוא כשהטקסט מוקרא לצורך נגישות המסך.
מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | text: "signup_with" |
בטבלה הבאה מפורטים כל הטקסטים הזמינים ללחצנים והתיאורים שלהם:
| טקסט | |
|---|---|
signin_with |
|
signup_with |
|
continue_with |
|
signin |
|
צורה
צורת הכפתור. ערך ברירת המחדל הוא rectangular. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | shape: "rectangular" |
בטבלה הבאה מפורטות צורות הכפתורים הזמינות והתיאורים שלהן:
| צורה | |
|---|---|
rectangular |
icon, הוא זהה ל-square.
|
pill |
icon, הוא זהה ל-circle.
|
circle |
standard, הוא זהה ל-pill.
|
square |
standard, הוא זהה ל-rectangular.
|
logo_alignment
היישור של הלוגו של Google. ערך ברירת המחדל הוא left. המאפיין הזה רלוונטי רק לסוג הלחצן standard. מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | logo_alignment: "center" |
בטבלה הבאה מפורטים היישורים הזמינים והתיאורים שלהם:
| logo_alignment | |
|---|---|
left |
|
center |
|
רוחב
הרוחב המינימלי של הלחצן, בפיקסלים. הרוחב המקסימלי הוא 400 פיקסלים.
מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | width: "400" |
לוקאל
זה שינוי אופציונלי. הצגת הטקסט של הלחצן באמצעות הלוקאל שצוין, אחרת ברירת המחדל היא חשבון Google של המשתמש או הגדרות הדפדפן. מוסיפים את הפרמטר hl ואת קוד השפה להוראת src כשמטעינים את הספרייה, לדוגמה: gsi/client?hl=<iso-639-code>.
אם המדיניות לא מוגדרת, המערכת משתמשת בהגדרת ברירת המחדל של הלוקאל בדפדפן או בהעדפה של המשתמש בסשן ב-Google. לכן, יכול להיות שמשתמשים שונים יראו גרסאות שונות של לחצנים מותאמים לשוק המקומי, ואולי גם בגדלים שונים.
מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | locale: "zh_CN" |
click_listener
אתם יכולים להגדיר פונקציית JavaScript שתיקרא כשלוחצים על הכפתור "כניסה באמצעות חשבון Google" באמצעות המאפיין click_listener.
google.accounts.id.renderButton(document.getElementById("signinDiv"), { theme: 'outline', size: 'large', click_listener: onClickHandler }); function onClickHandler(){ console.log("Sign in with Google button clicked...") }
בדוגמה הזו, ההודעה Sign in with Google button clicked... נרשמת במסוף כשלוחצים על הכפתור "כניסה באמצעות חשבון Google".
מדינה (State)
אופציונלי, מכיוון שאפשר להציג כמה כפתורי "כניסה באמצעות חשבון Google" באותו דף, אתם יכולים להקצות לכל כפתור מחרוזת ייחודית. אותה מחרוזת תוחזר יחד עם טוקן של מזהה, כדי שתוכלו לזהות על איזה כפתור המשתמש לחץ כדי להיכנס.
מידע נוסף מופיע בטבלה הבאה:
| סוג | חובה | דוגמה |
|---|---|---|
| מחרוזת | אופציונלי | data-state: "button 1" |
סוג הנתונים: פרטי כניסה
כשמפעילים את הפונקציה native_callback, אובייקט Credential מועבר כפרמטר. בטבלה הבאה מפורטים השדות שכלולים באובייקט:
| שדה | |
|---|---|
id |
מזהה את המשתמש. |
password |
הסיסמה |
שיטה: google.accounts.id.disableAutoSelect
כשהמשתמש יוצא מהאתר, צריך להפעיל את השיטה google.accounts.id.disableAutoSelect כדי לתעד את הסטטוס בקובצי Cookie. כך נמנעת לולאה אינסופית בחוויית המשתמש. קטע הקוד הבא מציג את השיטה:
google.accounts.id.disableAutoSelect()
בדוגמת הקוד הבאה מוטמעת השיטה google.accounts.id.disableAutoSelect עם פונקציית onSignout():
<script>
function onSignout() {
google.accounts.id.disableAutoSelect();
}
</script>
Method: google.accounts.id.storeCredential
ה-method הזו היא wrapper ל-method store() של ה-API המובנה בדפדפן לניהול פרטי כניסה. לכן, אפשר להשתמש בו רק כדי לאחסן פרטי כניסה של סיסמה. דוגמה לקוד של השיטה:
google.accounts.id.storeCredential(Credential, callback)
בדוגמת הקוד הבאה מוטמעת השיטה google.accounts.id.storeCredential עם פונקציית onSignIn():
<script>
function onSignIn() {
let cred = {id: '...', password: '...'};
google.accounts.id.storeCredential(cred);
}
</script>
Method: google.accounts.id.cancel
אפשר לבטל את תהליך ההתחברות בלחיצה אחת אם מסירים את ההודעה מה-DOM של הצד המסתמך. אם כבר נבחרה תעודה, פעולת הביטול לא תתבצע. דוגמה לקוד של השיטה:
google.accounts.id.cancel()
בדוגמת הקוד הבאה מוטמעת השיטה google.accounts.id.cancel() עם פונקציית onNextButtonClicked():
<script>
function onNextButtonClicked() {
google.accounts.id.cancel();
showPasswordPage();
}
</script>
קריאה חוזרת (callback) לטעינת הספרייה: onGoogleLibraryLoad
אפשר לרשום קריאה חוזרת (callback) של onGoogleLibraryLoad. היא מקבלת הודעה אחרי שספריית JavaScript של "כניסה באמצעות חשבון Google" נטענת:
window.onGoogleLibraryLoad = () => {
...
};
הקריאה החוזרת הזו היא רק קיצור דרך לקריאה החוזרת window.onload. אין הבדלים בהתנהגות.
דוגמת הקוד הבאה מטמיעה קריאה חוזרת (callback) של onGoogleLibraryLoad:
<script>
window.onGoogleLibraryLoad = () => {
google.accounts.id.initialize({
...
});
google.accounts.id.prompt();
};
</script>
השיטה: google.accounts.id.revoke
השיטה google.accounts.id.revoke מבטלת את הרשאת ה-OAuth שמשמשת לשיתוף של טוקן המזהה של המשתמש שצוין. הנה קטע הקוד של השיטה:
javascript
google.accounts.id.revoke(login_hint, callback)
| פרמטר | סוג | תיאור |
|---|---|---|
login_hint |
מחרוזת | כתובת האימייל או המזהה הייחודי של חשבון Google של המשתמש. המזהה הוא המאפיין sub של המטען הייעודי (payload) של פרטי הכניסה. |
callback |
פונקציה | RevocationResponse handler אופציונלי. |
בדוגמת הקוד הבאה אפשר לראות איך משתמשים ב-method revoke עם מזהה.
google.accounts.id.revoke('1618033988749895', done => {
console.log(done.error);
});סוג הנתונים: RevocationResponse
כשפונקציית callback מופעלת, אובייקט RevocationResponse מועבר כפרמטר. בטבלה הבאה מפורטים השדות שכלולים באובייקט התגובה לביטול:
| שדה | |
|---|---|
successful |
השדה הזה הוא הערך המוחזר של הפעלת ה-method. |
error |
השדה הזה יכול להכיל הודעת תגובה מפורטת לשגיאה. |
הפעולה בוצעה
השדה הזה הוא ערך בוליאני שמוגדר כ-true אם הקריאה ל-method revoke הצליחה, או כ-false אם היא נכשלה.
error
השדה הזה הוא ערך מחרוזת והוא מכיל הודעת שגיאה מפורטת אם הפעלת ה-method revoke נכשלה. אם הפעולה הצליחה, השדה לא מוגדר.