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

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

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

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

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

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

מאפיין
data-client_id מזהה הלקוח של האפליקציה
data-color_scheme ערכת הצבעים שמוחלת על ההנחיה לאישור בלחיצה אחת.
data-auto_prompt הצגת המנגנון "לחיצה אחת" של Google.
data-auto_select ההגדרה הזו מאפשרת בחירה אוטומטית ב-Google One Tap.
data-login_uri כתובת ה-URL של נקודת הקצה של הכניסה
data-callback שם הפונקציה של ה-handler של טוקן ה-ID ב-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 המערכת מדלגת על לחיצה אחת אם לקובץ ה-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 של הביניים. אם המאפיין הזה קיים, התהליך של לחיצה אחת פועל במצב iframe ביניים.
data-intermediate_iframe_close_callback המדיניות הזו מבטלת את התנהגות ברירת המחדל של iframe ביניים כשמשתמשים סוגרים ידנית את לחיצה אחת.
data-itp_support ההגדרה מאפשרת שימוש בממשק משתמש משודרג של לחיצה אחת בדפדפני ITP.
data-login_hint דילוג על בחירת החשבון על ידי מתן רמז למשתמש.
data-hd הגבלת בחירת החשבון לפי דומיין.
data-use_fedcm_for_prompt מאפשרים לדפדפן לשלוט בהנחיות למשתמשים להיכנס לחשבון ולנהל את תהליך הכניסה בין האתר שלכם לבין Google.
data-use_fedcm_for_button השדה הזה קובע אם צריך להשתמש בממשק משתמש של לחצן FedCM ב-Chrome (במחשב בגרסה M125 ואילך וב-Android בגרסה M128 ואילך). ברירת המחדל היא false.
data-button_auto_select האם להפעיל את האפשרות בחירה אוטומטית בתהליך של לחצן FedCM. אם האפשרות הזו מופעלת, משתמשים חוזרים עם סשן פעיל ב-Google ייכנסו אוטומטית, בלי שתופיע להם ההנחיה לבחירת חשבון. ערך ברירת המחדל הוא false.

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

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

data-client_id

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

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

data-color_scheme

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

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

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

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

data-auto_prompt

המאפיין הזה קובע אם להציג את התכונה 'הצטרפות בלחיצה אחת' או לא. ערך ברירת המחדל הוא 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 להפניה אוטומטית.

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

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

נקודת הקצה להתחברות צריכה לטפל בבקשות 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.

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

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

data-native_login_uri

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

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

data-native_callback

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

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

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

data-native_id_param

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

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

data-native_password_param

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

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

data-cancel_on_tap_outside

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

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

data-prompt_parent_id

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

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

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

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

data-nonce

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

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

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

data-essential_claims

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

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

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

data-context

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

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

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

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

הקשר
signin ‫"Sign in to"‏ (כניסה לחשבון)
signup "הרשמה אל"
use "שימוש"

data-moment_callback

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

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

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

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

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

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

data-ux_mode

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

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

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

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

data-allowed_parent_origin

המקורות שמותר להם להטמיע את ה-iframe של הביניים. התכונה 'הצטרפות בלחיצה אחת' פועלת במצב 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 לא תקין, האתחול של לחיצה אחת במצב 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 הביניים כשמשתמשים סוגרים ידנית את לחיצה אחת על ידי הקשה על הלחצן X בממשק המשתמש של לחיצה אחת. התנהגות ברירת המחדל היא להסיר את ה-iframe הביניים מ-DOM באופן מיידי.

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

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

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

data-itp_support

השדה הזה קובע אם להפעיל בדפדפנים שתומכים במניעת מעקב חכמה (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 רמז לגבי שם הדומיין. אם הפעולה מצליחה, חשבונות המשתמשים שמוצגים במהלך בחירת החשבון מוגבלים לדומיין שצוין. ערך של wildcard: * מציע למשתמש רק חשבונות 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 ואילך וב-Android בגרסה M128 ואילך). ברירת המחדל היא false. מידע נוסף מופיע בטבלה הבאה:

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

data-button_auto_select

השדה הזה קובע אם להפעיל את האפשרות בחירה אוטומטית בתהליך של לחצן FedCM. אם האפשרות הזו מופעלת, משתמשים חוזרים עם סשן פעיל ב-Google יתחברו אוטומטית, בלי שתופיע ההנחיה לבחירת חשבון. ברירת המחדל היא 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 | inside
גופן: ‎#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
כפתור רגיל עם התווית 'כניסה באמצעות חשבון Google' כפתור עם סמל בלי טקסט גלוי
טקסט הלחצן הוא 'כניסה באמצעות Google'.
signup_with
כפתור רגיל עם התווית 'הרשמה באמצעות חשבון Google' כפתור עם סמל בלי טקסט גלוי
הטקסט בלחצן הוא 'הרשמה באמצעות Google'.
continue_with
כפתור רגיל עם הכיתוב 'המשך עם Google' כפתור עם סמל בלי טקסט גלוי
הטקסט שמופיע על הלחצן הוא 'המשך עם Google'.
signin
כפתור רגיל עם התווית 'כניסה' כפתור עם סמל בלי טקסט גלוי
הטקסט של הלחצן הוא 'כניסה'.

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
לחצן רגיל עם הלוגו של Google בצד ימין
מיישר לימין את הלוגו של 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 של האסימון המזהה

נקודת הקצה של ה-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 מחרוזת אקראית שמשתנה עם כל בקשה לנקודת הכניסה שצוינה על ידי data-login_uri, חייבת להתאים לערך בפרמטר הבקשה g_csrf_token.
פרמטר של בקשה g_csrf_token מחרוזת אקראית שמשתנה עם כל בקשה לנקודת הקצה של הכניסה שצוינה על ידי data-login_uri, חייבת להתאים לערך של קובץ ה-Cookie‏ g_csrf_token.
פרמטר של בקשה credential אסימון מזהה JWT מקודד ש-Google מנפיקה.
פרמטר של בקשה select_by איך המשתמש נכנס לחשבון.
פרמטר של בקשה 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.@gmail.com
  • ‫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

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

select_by

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

  • המשתמש לחץ על הלחצן 'לחיצה אחת' או על הלחצן 'כניסה באמצעות חשבון Google', או השתמש בתהליך הכניסה האוטומטי ללא מגע.

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

  • לפני שמשתפים את פרטי הכניסה של טוקן ה-ID עם האפליקציה, המשתמש צריך

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

הערך של השדה הזה מוגדר לאחד מהסוגים הבאים:

ערך תיאור
auto כניסה אוטומטית של משתמש עם סשן קיים שבעבר הסכים לשיתוף פרטי הכניסה. ההגדרה רלוונטית רק לדפדפנים שלא תומכים ב-FedCM.
user משתמש עם סשן קיים שנתן בעבר הסכמה, לחץ על הלחצן 'המשך בתור' של אישור בלחיצה אחת כדי לשתף את פרטי הכניסה. ההגדרה רלוונטית רק לדפדפנים שלא תומכים ב-FedCM.
fedcm משתמש לחץ על הלחצן 'המשך בתור' של One Tap כדי לשתף פרטי כניסה באמצעות FedCM. ההגדרה חלה רק על דפדפנים עם תמיכה ב-FedCM.
fedcm_auto כניסה אוטומטית של משתמש עם סשן קיים שבעבר הסכים לשתף פרטי כניסה באמצעות FedCM One Tap. ההגדרה חלה רק על דפדפנים עם תמיכה ב-FedCM.
user_1tap משתמש עם סשן קיים לחץ על הכפתור 'המשך בתור' של One Tap כדי להביע הסכמה ולשתף את פרטי הכניסה. רלוונטי רק ל-Chrome מגרסה 75 ואילך.
user_2tap משתמש בלי סשן קיים לחץ על הלחצן 'המשך בתור' של One Tap כדי לבחור חשבון, ואז לחץ על הלחצן 'אישור' בחלון קופץ כדי לתת הסכמה ולשתף את פרטי הכניסה. ההגדרה חלה על דפדפנים שלא מבוססים על Chromium.
itp משתמש שהעניק בעבר הסכמה, לחץ על 'הסכמה בלחיצה אחת' בדפדפנים עם ITP.
itp_confirm משתמש שלא העניק הסכמה לחץ על לחיצה אחת בדפדפני ITP ולחץ על הלחצן 'המשך' כדי להעניק הסכמה ולשתף את פרטי הכניסה.
btn משתמש שנתן בעבר הסכמה, לחץ על הלחצן 'כניסה באמצעות חשבון Google' ובחר חשבון Google מתוך 'בחירת חשבון' כדי לשתף את פרטי הכניסה.
btn_confirm משתמש שלא נתן הסכמה לחץ על הכפתור 'כניסה באמצעות חשבון Google' ואז על הכפתור 'המשך' כדי לתת הסכמה ולשתף את פרטי הכניסה.

הסמוי הסופי

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

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

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

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

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

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