מאמר עזרה בנושא Sign in with Google HTML API

בדף העזר הזה מתואר ה-API של מאפייני הנתונים ב-HTML של "כניסה באמצעות חשבון Google", שמשמש להצגת הלחצן "כניסה באמצעות חשבון Google" או ההודעה של One Tap בדפי אינטרנט.

רכיב עם המזהה "g_id_onload"

אתם יכולים להוסיף מאפייני נתונים של "כניסה באמצעות חשבון Google" לכל רכיב גלוי או בלתי נראה, כמו <div> ו-<span>. הדרישה היחידה היא שמזהה הרכיב יהיה מוגדר כ-g_id_onload. אל תגדירו את המזהה הזה לכמה רכיבים.

מאפייני נתונים

בטבלה הבאה מפורטים מאפייני הנתונים והתיאורים שלהם:

מאפיין
data-client_id מזהה הלקוח של האפליקציה
data-color_scheme ערכת הצבעים שמוחלת על ההודעה של One Tap.
data-auto_prompt הצגת המנגנון "לחיצה אחת" של Google.
data-auto_select הפעלת בחירה אוטומטית במנגנון "לחיצה אחת" של Google.
data-login_uri כתובת ה-URL של נקודת הקצה להתחברות
data-callback שם הפונקציה של ה-handler של טוקן המזהה ב-JavaScript
data-native_login_uri כתובת ה-URL של נקודת הקצה של ה-handler של פרטי הכניסה באמצעות סיסמה
data-native_callback שם הפונקציה של ה-handler של פרטי הכניסה באמצעות סיסמה ב-JavaScript
data-native_id_param שם הפרמטר של הערך credential.id
data-native_password_param שם הפרמטר של הערך credential.password
data-cancel_on_tap_outside המדיניות קובעת אם לבטל את ההנחיה אם המשתמש לוחץ מחוץ להנחיה.
data-prompt_parent_id מזהה ה-DOM של רכיב המאגר של ההודעה לאימות בלחיצה אחת
data-skip_prompt_cookie המערכת מדלגת על One Tap אם קובץ ה-Cookie שצוין מכיל ערך לא ריק.
data-nonce מחרוזת אקראית לטוקנים של מזהים
data-essential_claims הצהרות נוספות שצריך לכלול בטוקן של המזהה ש-Google מחזירה.
data-context הכותרת והמילים בהודעה של "כניסה בנגיעה אחת"
data-moment_callback שם הפונקציה של המאזין להתראות על סטטוס ממשק המשתמש של ההנחיה
data-state_cookie_domain אם צריך להפעיל את One Tap בדומיין הראשי ובתת-הדומיינים שלו, צריך להעביר את הדומיין הראשי למאפיין הזה כדי שייעשה שימוש בקובץ Cookie משותף אחד.
data-ux_mode תהליך חוויית המשתמש של הכפתור "כניסה באמצעות חשבון Google"
data-allowed_parent_origin המקורות שמורשים להטמיע את ה-iframe המתווך. אם המאפיין הזה קיים, One Tap פועל במצב iframe ביניים.
data-intermediate_iframe_close_callback מבטלת את התנהגות ברירת המחדל של iframe הביניים כשמשתמשים סוגרים ידנית את One Tap.
data-itp_support הפעלת חוויית משתמש משודרגת של One Tap בדפדפנים עם ITP.
data-login_hint דילוג על בחירת החשבון על ידי מתן רמז למשתמש.
data-hd הגבלת בחירת החשבון לפי דומיין.
data-use_fedcm_for_prompt מאפשרים לדפדפן לשלוט בהצעות למשתמשים להיכנס לחשבון ולתווך בתהליך הכניסה בין האתר שלכם לבין Google.
data-use_fedcm_for_button השדה הזה קובע אם להשתמש בממשק המשתמש של FedCM עם כפתור ב-Chrome (גרסה M125 ואילך במחשב וגרסה M128 ואילך ב-Android). ערך ברירת המחדל הוא false.
data-button_auto_select אם להפעיל את האפשרות בחירה אוטומטית בתהליך של FedCM באמצעות כפתור. אם האפשרות הזו מופעלת, משתמשים חוזרים עם סשן פעיל ב-Google יתחברו באופן אוטומטי, בלי לעבור דרך ההנחיה של Account Chooser. ערך ברירת המחדל הוא false.

סוגי מאפיינים

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

data-client_id

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

סוג חובה דוגמה
מחרוזת כן data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-color_scheme

השדה הזה הוא ערכת הצבעים שמוחלת על ההודעה של One Tap. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת זה שינוי אופציונלי. כברירת מחדל, ערכת הצבעים של המערכת של המשתמשים. data-color_scheme="dark"

בטבלה הבאה מפורטות ערכות הצבעים הזמינות והתיאורים שלהן.

ערכת צבעים
default החלת ערכת הצבעים שמוגדרת כברירת מחדל במערכת של המשתמש, בהתאם להעדפה של המשתמש (ערכת צבעים בהירה או כהה).
light החלת ערכת צבעים בהירה.
dark להחיל ערכת צבעים כהה.

data-auto_prompt

המאפיין הזה קובע אם להציג את One Tap או לא. ערך ברירת המחדל הוא true. התכונה "כניסה ב-Google בלחיצה אחת" לא מוצגת כשהערך הזה הוא false. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
בוליאני אופציונלי data-auto_prompt="true"

data-auto_select

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

סוג חובה דוגמה
בוליאני אופציונלי data-auto_select="true"

data-login_uri

המאפיין הזה הוא ה-URI של נקודת הקצה להתחברות.

הערך חייב להתאים בדיוק לאחד ממזהי ה-URI המורשים להפניה אוטומטית של לקוח OAuth 2.0, שהגדרתם בפלטפורמת האימות של Google, והוא חייב לעמוד בכללי האימות של מזהי URI להפניה אוטומטית.

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

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

נקודת הקצה (endpoint) של ההתחברות צריכה לטפל בבקשות POST שמכילות פרמטר credential עם ערך של טוקן מזהה בגוף הבקשה.

מידע נוסף מופיע בטבלה הבאה:

סוג אופציונלי דוגמה
כתובת URL ברירת המחדל היא ה-URI של הדף הנוכחי, או הערך שאתם מציינים.
המערכת מתעלמת מהמדיניות הזו כשמוגדרות המדיניות data-ux_mode="popup" ו-data-callback.
data-login_uri="https://www.example.com/login"

data-callback

המאפיין הזה הוא השם של פונקציית ה-JavaScript שמטפלת בטוקן של מזהה שמוחזר. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת חובה אם לא הוגדר data-login_uri. data-callback="handleToken"

אפשר להשתמש באחד מהמאפיינים data-login_uri ו-data-callback. היא תלויה בהגדרות הבאות של הרכיב ומצב חוויית המשתמש:

  • המאפיין data-login_uri נדרש למצב חוויית המשתמש redirect של הכפתור "כניסה באמצעות חשבון Google", שמתעלם מהמאפיין data-callback.

  • צריך להגדיר אחד משני המאפיינים האלה למצב חוויית המשתמש popup של Google One Tap ושל כפתור הכניסה באמצעות חשבון Google. אם שניהם מוגדרים, למאפיין data-callback יש עדיפות גבוהה יותר.

פונקציות JavaScript בתוך מרחב שמות לא נתמכות על ידי ה-API בפורמט HTML. במקום זאת, צריך להשתמש בפונקציית JavaScript גלובלית בלי מרחב שמות. לדוגמה, צריך להשתמש ב-mylibCallback במקום ב-mylib.callback.

פונקציית הקריאה החוזרת מקבלת אובייקט CredentialResponse כפרמטר. במאמר CredentialResponse מפורטים ערכי התגובה האפשריים.

data-native_login_uri

המאפיין הזה הוא כתובת ה-URL של נקודת הקצה של ה-handler של פרטי הכניסה באמצעות סיסמה. אם מגדירים את המאפיין data-native_login_uri או את המאפיין data-native_callback, ספריית ה-JavaScript חוזרת ל-Credential Manager המובנה כשאין סשן של Google. אי אפשר להגדיר גם את המאפיין data-native_callback וגם את המאפיין data-native_login_uri. מידע נוסף מפורט בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-login_uri="https://www.example.com/password_login"

data-native_callback

המאפיין הזה הוא השם של פונקציית ה-JavaScript שמטפלת בפרטי הכניסה של הסיסמה שמוחזרים מ-Credential Manager המובנה של הדפדפן. אם מגדירים את המאפיין data-native_login_uri או את המאפיין data-native_callback, ספריית ה-JavaScript חוזרת ל-Credential Manager המובנה כשאין סשן של Google. אסור להגדיר גם את data-native_callback וגם את data-native_login_uri. בטבלה הבאה מפורט מידע נוסף:

סוג חובה דוגמה
מחרוזת אופציונלי data-native_callback="handlePasswordCredential"

פונקציות JavaScript בתוך מרחב שמות לא נתמכות על ידי ה-API בפורמט HTML. במקום זאת, צריך להשתמש בפונקציית JavaScript גלובלית בלי מרחב שמות. לדוגמה, צריך להשתמש ב-mylibCallback במקום ב-mylib.callback.

data-native_id_param

כששולחים את פרטי הכניסה של הסיסמה לנקודת הקצה של ה-handler של פרטי הכניסה של הסיסמה, אפשר לציין את שם הפרמטר של השדה credential.id. שם ברירת המחדל הוא email. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
כתובת URL אופציונלי data-native_id_param="user_id"

data-native_password_param

כששולחים את פרטי הכניסה של הסיסמה לנקודת הקצה של ה-handler של פרטי הכניסה של הסיסמה, אפשר לציין את שם הפרמטר של הערך credential.password. שם ברירת המחדל הוא password. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
כתובת URL אופציונלי data-native_password_param="pwd"

data-cancel_on_tap_outside

המאפיין הזה קובע אם לבטל את הבקשה של One Tap אם המשתמש לוחץ מחוץ להנחיה. ערך ברירת המחדל הוא true. כדי להשבית את המדיניות, מגדירים את הערך false. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
בוליאני אופציונלי data-cancel_on_tap_outside="false"

data-prompt_parent_id

המאפיין הזה מגדיר את מזהה ה-DOM של רכיב מאגר התגים. אם המדיניות לא מוגדרת, ההודעה של One Tap מוצגת בפינה הימנית העליונה של החלון. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-prompt_parent_id="parent_id"

משתמש בקובץ Cookie כדי לשלוט בהצגת ההודעה של One Tap. אם קובץ ה-Cookie שצוין במאפיין הזה מכיל ערך שאינו ריק, ההודעה לא מוצגת. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-skip_prompt_cookie="SID"

data-nonce

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

סוג חובה דוגמה
מחרוזת אופציונלי data-nonce="biaqbm70g23"

אורך ה-nonce מוגבל לגודל המקסימלי של JWT שנתמך בסביבה שלכם, ולמגבלות הגודל של HTTP בדפדפן ובשרת הספציפיים.

data-essential_claims

המאפיין הזה הוא מחרוזת שמשמשת לבקשת הצהרות נוספות שייכללו בטוקן של מזהה ש-Google מחזירה. כאן מופיעה רשימה מלאה של ההצהרות ש-Google מקבלת.

מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-essential_claims="auth_time, amr"

data-context

השדה הזה משנה את הטקסט של הכותרת וההודעות שמוצגות בהודעה של One Tap, ואין לו השפעה על דפדפני ITP. ברירת המחדל היא signin.

מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-context="use"

בטבלה הבאה מפורטים כל ההקשרים הזמינים והתיאורים שלהם:

הקשר
signin "כניסה אל"
signup "הרשמה אל"
use "שימוש"

data-moment_callback

המאפיין הזה הוא שם הפונקציה של המאזין להתראות סטטוס של ממשק המשתמש של ההנחיה. למידע נוסף, קראו על סוג הנתונים PromptMomentNotification.

מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-moment_callback="logMomentNotification"

פונקציות JavaScript בתוך מרחב שמות לא נתמכות על ידי ה-API בפורמט HTML. במקום זאת, צריך להשתמש בפונקציית JavaScript גלובלית בלי מרחב שמות. לדוגמה, צריך להשתמש ב-mylibCallback במקום ב-mylib.callback.

אם אתם צריכים להציג את One Tap בדומיין הורה ובתת-הדומיינים שלו, העבירו את דומיין ההורה למאפיין הזה כדי להשתמש בקובץ Cookie אחד במצב משותף. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-state_cookie_domain="example.com"

data-ux_mode

המאפיין הזה מגדיר את תהליך חוויית המשתמש של הכפתור "כניסה באמצעות חשבון Google". ערך ברירת המחדל הוא popup. למאפיין הזה אין השפעה על חוויית המשתמש של One Tap. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-ux_mode="redirect"

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

מצב UX
popup מבצע את תהליך הכניסה לחשבון בחלון קופץ.
redirect מבצע את תהליך הכניסה של חוויית המשתמש באמצעות הפניה אוטומטית לדף מלא.

data-allowed_parent_origin

המקורות שמורשים להטמיע את ה-iframe המתווך. אם המאפיין הזה קיים, One Tap פועל במצב iframe ביניים. מידע נוסף מפורט בטבלה הבאה:

סוג חובה דוגמה
מחרוזת או מערך מחרוזות אופציונלי data-allowed_parent_origin="https://example.com"

בטבלה הבאה מפורטים סוגי הערכים הנתמכים והתיאורים שלהם.

סוגי ערכים
string URI של דומיין אחד. "https://example.com"
string array רשימה של מזהי URI של דומיינים, מופרדים בפסיקים. "https://news.example.com,https://local.example.com"

אם הערך של המאפיין data-allowed_parent_origin לא תקין, ההפעלה של One Tap במצב iframe ביניים תיכשל ותיפסק.

יש גם תמיכה בקידומות של תווים כלליים לחיפוש. לדוגמה, "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" נחשב לא חוקי.

data-intermediate_iframe_close_callback

מבטלת את התנהגות ברירת המחדל של iframe הביניים כשמשתמשים סוגרים ידנית את One Tap על ידי לחיצה על הלחצן "X" בממשק המשתמש של One Tap. פעולת ברירת המחדל היא להסיר את ה-iframe המתווך מה-DOM באופן מיידי.

השדה data-intermediate_iframe_close_callback נכנס לתוקף רק במצב iframe ביניים. והיא משפיעה רק על ה-iframe המתווך, במקום על ה-iframe של One Tap. ממשק המשתמש של One Tap מוסר לפני שהקריאה החוזרת מופעלת.

סוג חובה דוגמה
פונקציה אופציונלי data-intermediate_iframe_close_callback="logBeforeClose"

פונקציות JavaScript בתוך מרחב שמות לא נתמכות על ידי ה-API בפורמט HTML. במקום זאת, צריך להשתמש בפונקציית JavaScript גלובלית בלי מרחב שמות. לדוגמה, צריך להשתמש ב-mylibCallback במקום ב-mylib.callback.

data-itp_support

השדה הזה קובע אם חוויית המשתמש המשודרגת של One Tap תופעל בדפדפנים שתומכים במניעת מעקב חכמה (ITP). ערך ברירת המחדל הוא false. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
בוליאני אופציונלי data-itp_support="false"

data-login_hint

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

למידע נוסף, קראו את מסמכי התיעוד של OpenID Connect בנושא login_hint.

סוג חובה דוגמה
מחרוזת. יכול להיות כתובת אימייל או ערך השדה sub מטוקן של מזהה. אופציונלי data-login_hint="elisa.beckett@gmail.com"

data-hd

אם למשתמש יש כמה חשבונות והוא צריך להיכנס רק באמצעות חשבון Workspace, אפשר להשתמש בהגדרה הזו כדי לספק ל-Google רמז לשם הדומיין. אם הפעולה מצליחה, חשבונות המשתמשים שמוצגים במהלך בחירת החשבון מוגבלים לדומיין שצוין. ערך של תו כללי לחיפוש: * מציע למשתמש רק חשבונות Workspace ולא כולל חשבונות פרטיים (user@gmail.com) במהלך בחירת החשבון.

למידע נוסף, קראו את מסמכי התיעוד של OpenID Connect בנושא hd.

סוג חובה דוגמה
מחרוזת. שם דומיין שמוגדר במלואו או *. אופציונלי data-hd="*"

data-use_fedcm_for_prompt

מאפשרים לדפדפן לשלוט בהצעות למשתמשים להיכנס לחשבון ולתווך בתהליך הכניסה לחשבון בין האתר שלכם לבין Google. ערך ברירת המחדל הוא false. מידע נוסף זמין בדף מעבר ל-FedCM.

סוג חובה דוגמה
בוליאני הוצא משימוש data-use_fedcm_for_prompt="true"

data-use_fedcm_for_button

השדה הזה קובע אם להשתמש בחוויית המשתמש של FedCM עם כפתור ב-Chrome (גרסה M125 ואילך במחשב וגרסה M128 ואילך ב-Android). ערך ברירת המחדל הוא false. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
בוליאני אופציונלי data-use_fedcm_for_button="true"

data-button_auto_select

השדה הזה קובע אם להפעיל את האפשרות בחירה אוטומטית בתהליך של FedCM באמצעות כפתור. אם המדיניות מופעלת, משתמשים חוזרים עם סשן פעיל ב-Google יתחברו באופן אוטומטי, בלי לעבור דרך ההנחיה של Account Chooser. ערך ברירת המחדל הוא false. צריך להפעיל באופן מפורש את הכניסה האוטומטית באמצעות כפתור במהלך ההשקה של ההצטרפות. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
בוליאני אופציונלי data-button_auto_select="true"

רכיב עם המחלקה "g_id_signin"

אם מוסיפים את g_id_signin למאפיין class של רכיב, הרכיב מוצג כלחצן "כניסה באמצעות חשבון Google".

אפשר להציג כמה לחצני "כניסה באמצעות חשבון Google" באותו דף. לכל כפתור יכולות להיות הגדרות חזותיות משלו. ההגדרות נקבעות לפי מאפייני הנתונים הבאים.

מאפייני נתונים חזותיים

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

מאפיין
data-type סוג הכפתור: סמל או כפתור רגיל.
data-theme עיצוב הכפתור. לדוגמה, filled_blue או filled_black.
data-size גודל הכפתור. לדוגמה, קטן או גדול.
data-text הטקסט של הכפתור. לדוגמה, "כניסה באמצעות חשבון Google" או "הרשמה באמצעות חשבון Google".
data-shape צורת הכפתור. לדוגמה, מלבני או עגול.
data-logo_alignment יישור הלוגו של Google: לשמאל או למרכז.
data-width רוחב הכפתור בפיקסלים.
data-locale הטקסט של הלחצן מוצג בשפה שמוגדרת במאפיין הזה.
data-click_listener אם מגדירים את הפונקציה הזו, המערכת קוראת לה כשלוחצים על הכפתור "כניסה באמצעות חשבון Google".
data-state אם מגדירים את המחרוזת הזו, היא מוחזרת עם הטוקן של המזהה.

סוגי מאפיינים

בקטעים הבאים מפורטים הסוג של כל מאפיין ודוגמה לשימוש בו.

data-type

סוג הכפתור. ערך ברירת המחדל הוא standard. בטבלה הבאה מפורט מידע נוסף:

סוג חובה דוגמה
מחרוזת כן data-type="icon"

בטבלה הבאה מפורטים כל סוגי הלחצנים הזמינים והתיאורים שלהם:

סוג
standard
כפתור עם טקסט או מידע מותאם אישית.
icon
כפתור סמל בלי טקסט.

data-theme

עיצוב הכפתור. ערך ברירת המחדל הוא outline. בטבלה הבאה מפורט מידע נוסף:

סוג חובה דוגמה
מחרוזת אופציונלי data-theme="filled_blue"

בטבלה הבאה מפורטים העיצובים הזמינים והתיאורים שלהם:

עיצוב דוגמאות מפרטים
outline
standard-button-white icon-button-white personalized-button-white
עיצוב רגיל של כפתור.
מילוי: ‎#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

data-size

גודל הכפתור. ערך ברירת המחדל הוא large. בטבלה הבאה מפורט מידע נוסף:

סוג חובה דוגמה
מחרוזת אופציונלי data-size="small"

בטבלה הבאה מפורטים הגדלים הזמינים של הכפתורים והתיאורים שלהם.

גודל
large
כפתור רגיל גדול כפתור גדול בצורת סמל כפתור גדול בהתאמה אישית
כפתור גדול.
medium
כפתור רגיל בגודל בינוני כפתור בצורת סמל בינוני
כפתור בגודל בינוני.
small
כפתור כניסה קטן כפתור קטן בצורת סמל
כפתור קטן.

data-text

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

מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-text="signup_with"

בטבלה הבאה מפורטים הטקסטים הזמינים ללחצנים והתיאורים שלהם:

טקסט
signin_with
כפתור רגיל עם התווית &quot;כניסה באמצעות חשבון Google&quot; כפתור סמל בלי טקסט גלוי
הטקסט של הלחצן הוא "כניסה באמצעות חשבון Google".
signup_with
כפתור רגיל עם התווית &quot;הרשמה באמצעות חשבון Google&quot; כפתור סמל בלי טקסט גלוי
הטקסט של הלחצן הוא "הרשמה באמצעות חשבון Google".
continue_with
כפתור רגיל עם התווית &quot;המשך באמצעות חשבון Google&quot; כפתור סמל בלי טקסט גלוי
הטקסט של הכפתור הוא "המשך באמצעות חשבון Google".
signin
כפתור רגיל עם התווית &quot;כניסה&quot; כפתור סמל בלי טקסט גלוי
הטקסט של הכפתור הוא "כניסה".

data-shape

צורת הכפתור. ערך ברירת המחדל הוא rectangular. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-shape="rectangular"

בטבלה הבאה מפורטות צורות הכפתורים הזמינות והתיאורים שלהן:

צורה
rectangular
כפתור מלבני רגיל כפתור בצורת סמל מלבני כפתור מלבני בהתאמה אישית
הכפתור המלבני. אם משתמשים בו לסוג הלחצן icon, הוא זהה ל-square.
pill
כפתור רגיל בצורת גלולה כפתור בצורת סמל אליפטי כפתור מותאם אישית בצורת גלולה
הכפתור בצורת גלולה. אם משתמשים בו לסוג הלחצן icon, הוא זהה ל-circle.
circle
כפתור עגול רגיל כפתור עגול עם סמל כפתור עגול בהתאמה אישית
הכפתור בצורת עיגול. אם משתמשים בו לסוג הלחצן standard, הוא זהה ל-pill.
square
כפתור ריבוע רגיל כפתור בצורת סמל מרובע כפתור מרובע בהתאמה אישית
הכפתור בצורת ריבוע. אם משתמשים בו לסוג הלחצן standard, הוא זהה ל-rectangular.

data-logo_alignment

היישור של הלוגו של Google. ערך ברירת המחדל הוא left. המאפיין הזה רלוונטי רק לסוג הלחצן standard. מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-logo_alignment="center"

בטבלה הבאה מפורטים היישורים הזמינים והתיאורים שלהם:

logo_alignment
left
כפתור רגיל עם הלוגו של G בצד ימין
יישור הלוגו של Google לשמאל.
center
כפתור רגיל עם הלוגו של G במרכז
מיישר את הלוגו של Google למרכז.

data-width

הרוחב המינימלי של הלחצן, בפיקסלים. הרוחב המקסימלי הוא 400 פיקסלים.

מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-width=400

data-locale

זה שינוי אופציונלי. הצגת הטקסט של הלחצן באמצעות הלוקאל שצוין, אחרת ברירת המחדל היא חשבון Google של המשתמש או הגדרות הדפדפן. מוסיפים את הפרמטר hl ואת קוד השפה להוראת src כשמטעינים את הספרייה, לדוגמה: gsi/client?hl=<iso-639-code>.

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

מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-locale="zh_CN"

data-click_listener

אתם יכולים להגדיר פונקציית JavaScript שתיקרא כשלוחצים על הכפתור "כניסה באמצעות חשבון Google" באמצעות המאפיין data-click_listener.

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

בדוגמה הזו, ההודעה Sign in with Google button clicked...‎ נרשמת במסוף כשלוחצים על הכפתור "כניסה באמצעות חשבון Google".

data-state

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

מידע נוסף מופיע בטבלה הבאה:

סוג חובה דוגמה
מחרוזת אופציונלי data-state="button 1"

שילוב בצד השרת

נקודות הקצה בצד השרת צריכות לטפל בבקשות ה-HTTP הבאות מסוג POST.

נקודת הקצה של ה-handler של טוקן המזהה

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

דוגמה לבקשה לנקודת הקצה של ההתחברות:

POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: g_csrf_token=<RANDOM_STRING>
Host: www.example.com

credential=<JWT_ENCODED_ID_TOKEN>&g_csrf_token=<RANDOM_STRING>

בקשת ה-HTTP POST מכילה את הפרטים הבאים:

פורמט שם תיאור
קובץ Cookie g_csrf_token מחרוזת אקראית שמשתנה בכל בקשה לנקודת הקצה (endpoint) של ההתחברות שצוינה על ידי data-login_uri, חייבת להתאים לערך בפרמטר הבקשה g_csrf_token.
פרמטר של בקשה g_csrf_token מחרוזת אקראית שמשתנה בכל בקשה לנקודת הקצה של ההתחברות שצוינה על ידי data-login_uri, חייבת להתאים לערך של קובץ ה-Cookie‏ g_csrf_token.
פרמטר של בקשה credential הטוקן המקודד של מזהה ה-JWT ש-Google מנפיקה.
פרמטר של בקשה state הפרמטר הזה מוגדר רק כשהמשתמש לוחץ על כפתור "כניסה באמצעות חשבון Google" כדי להיכנס, ומצוין המאפיין state של הכפתור.

מסמך לאימות

אחרי פענוח, טוקן של מזהה נראה כמו בדוגמה הבאה:

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": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion creation time
  "exp": 1596477600, // Unix timestamp of the assertion expiration time
  "jti": "abc161803398874def"
}

הלקוחות חייבים להתעלם ממידע לא מזוהה מ-JWT.

השדה 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_verified יכול להיות נכון, כי Google אימתה את המשתמש כשיצר את חשבון Google, אבל יכול להיות שהבעלות על החשבון אצל הצד השלישי השתנתה מאז.

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

g_csrf_token

טוקן מצב למניעת זיוף. זהו אסימון של זיוף בקשות בין אתרים (CSRF) שנוצר על ידי הספרייה gsi/client. ערך אקראי נכלל גם כקובץ Cookie וגם כפרמטר של בקשה בגוף המטען הייעודי (payload) של ה-POST. אם שני הערכים האלה לא תואמים כשמעבדים את הבקשה בשרת, הבקשה נחשבת לא חוקית.

מדינה (State)

הפרמטר הזה מוגדר רק כשמשתמש לוחץ על כפתור "כניסה באמצעות חשבון Google" כדי להיכנס, ומצוין המאפיין data-state של הכפתור שנלחץ. הערך של השדה הזה זהה לערך שציינתם במאפיין data-state של הכפתור.

אפשר להציג כמה כפתורי "כניסה באמצעות חשבון Google" באותו דף, ולכן אתם יכולים להקצות לכל כפתור מחרוזת ייחודית. לכן, אפשר להשתמש בפרמטר state כדי לזהות על איזה כפתור המשתמש לחץ כדי להיכנס לחשבון.

נקודת קצה (endpoint) של handler לפרטי כניסה באמצעות סיסמה

נקודת הקצה של ה-handler של פרטי הכניסה באמצעות סיסמה מעבדת את פרטי הכניסה באמצעות סיסמה ש-Credential Manager המובנה מאחזר.

בקשת ה-HTTP POST מכילה את הפרטים הבאים:

פורמט שם תיאור
קובץ Cookie g_csrf_token מחרוזת אקראית שמשתנה בכל בקשה לנקודת הקצה (endpoint) של ההתחברות שצוינה על ידי data-native_login_uri, חייבת להתאים לערך בפרמטר הבקשה g_csrf_token.
פרמטר של בקשה g_csrf_token מחרוזת אקראית שמשתנה בכל בקשה לנקודת הקצה של ההתחברות שצוינה על ידי data-native_login_uri, חייבת להתאים לערך של קובץ ה-Cookie‏ g_csrf_token.
פרמטר של בקשה email טוקן של מזהה ש-Google מנפיקה.
פרמטר של בקשה password איך נבחרים פרטי הכניסה.