שירותי הזהויות של Google עוברים לממשקי API של FedCM. פועלים לפי ההוראות במדריך להעברת נתונים (מיגרציה) כדי לבדוק את השינויים האפשריים ולמנוע השפעות שליליות על הכניסה של המשתמשים לאתר.

דף זה תורגם על ידי Cloud Translation API.

הפניית API של כניסה באמצעות חשבון Google

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

שיטה: google.accounts.id.initialize

השיטה google.accounts.id.initialize מאתחלת את הלקוח של 'כניסה באמצעות חשבון Google' על סמך אובייקט התצורה. דוגמה לקוד של השיטה:

google.accounts.id.initialize(IdConfiguration)

הקוד לדוגמה הבא מיישם את ה-method 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>

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

צריך להפעיל את השיטה google.accounts.id.initialize רק פעם אחת, גם אם משתמשים במספר מודולים (כמו One Tap, לחצן מותאם אישית, ביטול וכו') באותו דף אינטרנט.
אם שולחים קריאה ל-method google.accounts.id.initialize כמה פעמים, המערכת תשמור את ההגדרות מהקריאה האחרונה ותשתמש בהן.

למעשה, אתם מאפסים את ההגדרות בכל פעם שאתם קוראים ל-method‏ google.accounts.id.initialize, וכל השיטות הבאות באותו דף אינטרנט משתמשות בהגדרות החדשות באופן מיידי.

סוג הנתונים: IdConfiguration

בטבלה הבאה מפורטים השדות והתיאורים של סוג הנתונים IdConfiguration:

שדה
`client_id`	מזהה הלקוח של האפליקציה
`auto_select`	הפעלת הבחירה האוטומטית.
`callback`	פונקציית JavaScript שמטפלת באסימונים מזהים. המאפיין הזה משמש את Google One Tap ואת מצב UX של הלחצן `popup` 'כניסה באמצעות חשבון Google'.
`login_uri`	כתובת ה-URL של נקודת הקצה להתחברות. המאפיין הזה משמש את הלחצן 'כניסה באמצעות חשבון Google' במצב `redirect` UX.
`native_callback`	פונקציית JavaScript שמטפלת בפרטי הכניסה של הסיסמאות.
`cancel_on_tap_outside`	ביטול ההנחיה אם המשתמש לוחץ מחוץ להנחיה.
`prompt_parent_id`	מזהה ה-DOM של רכיב הקונטיינר של ההנחיה בהקשה אחת
`nonce`	מחרוזת אקראית לאסימונים מזהים
`context`	הכותרת והמילים שבהנחיה 'הקשה אחת'
`state_cookie_domain`	אם אתם צריכים להפעיל את One Tap בדומיין ההורה ובתת-הדומיינים שלו, עליכם להעביר את הדומיין ההורה לשדה הזה כדי שנעשה שימוש בקובץ cookie משותף אחד.
`ux_mode`	תהליך ממשק המשתמש של הלחצן 'כניסה באמצעות חשבון Google'
`allowed_parent_origin`	המקורות שמורשים להטמיע את iframe הביניים. הקשה אחת תפעל במצב ביניים של iframe, אם שדה זה קיים.
`intermediate_iframe_close_callback`	המדיניות הזו מבטלת את התנהגות ברירת המחדל של iframe ביניים כשמשתמשים סוגרים את התכונה 'הקשה אחת' באופן ידני.
`itp_support`	הפעלת ממשק משתמש משודרג של One Tap בדפדפני ITP.
`login_hint`	ניתן לספק רמז למשתמש כדי לדלג על בחירת החשבון.
`hd`	להגביל את בחירת החשבונות לפי דומיין.
`use_fedcm_for_prompt`	מאפשרים לדפדפן לשלוט בהנחיות לכניסה של המשתמשים ולתווך את תהליך הכניסה בין האתר ל-Google.
`enable_redirect_uri_validation`	מפעילים תהליך הפניה אוטומטית של לחצן שעומד בדרישות של כללי האימות של URI להפניה אוטומטית.

client_id

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

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

auto_select

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

סוג	חובה	דוגמה
בוליאני	אופציונלי	`auto_select: true`

קריאה חוזרת (callback)

השדה הזה הוא פונקציית JavaScript שמטפלת באסימון המזהה שמוחזר מההנחיה One Tap או מהחלון הקופץ. המאפיין הזה נדרש אם נעשה שימוש במצב UX בעזרת Google One Tap או הלחצן 'כניסה באמצעות חשבון Google' popup. מידע נוסף זמין בטבלה הבאה:

סוג	חובה	דוגמה
פונקציה	נדרשת להקשה אחת ולמצב UX‏ `popup`	`callback: handleResponse`

login_uri

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

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

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

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

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

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

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

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

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

native_callback

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

סוג	חובה	דוגמה
פונקציה	אופציונלי	`native_callback: handleResponse`

cancel_on_tap_outside

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

סוג	חובה	דוגמה
בוליאני	אופציונלי	`cancel_on_tap_outside: false`

prompt_parent_id

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

סוג	חובה	דוגמה
מחרוזת	אופציונלי	`prompt_parent_id: 'parent_id'`

צופן חד-פעמי (nonce)

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

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

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

context

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

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

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

הקשר
`signin`	'כניסה באמצעות חשבון Google'
`signup`	'הרשמה באמצעות חשבון Google'
`use`	'שימוש עם Google'

state_cookie_domain

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

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

ux_mode

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

סוג	חובה	דוגמה
מחרוזת	אופציונלי	`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 ולתת-הדומיינים שלו. אפשר גם להשתמש במערך כדי לייצג 2 דומיינים שונים. לדוגמה, ["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 מוסר לפני שהקריאה החוזרת מופעלת.

סוג	חובה	דוגמה
פונקציה	אופציונלי	`intermediate_iframe_close_callback: logBeforeClose`

itp_support

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

סוג	חובה	דוגמה
בוליאני	אופציונלי	`itp_support: true`

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`

enable_redirect_uri_validation

מפעילים תהליך הפניה אוטומטית של לחצן שעומד בכללים לאימות URI של הפניה אוטומטית.

סוג	חובה	דוגמה
בוליאני	אופציונלי	`enable_redirect_uri_validation: true`

שיטה: google.accounts.id.prompt

השיטה google.accounts.id.prompt מציגה את ההנחיה להקשה אחת או את מנהל פרטי הכניסה המקורי של הדפדפן אחרי שמפעילים את השיטה initialize(). דוגמה לקוד של השיטה:

 google.accounts.id.prompt(/**
 @type{(function(!PromptMomentNotification):void)=} */ momentListener)

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

ההתראות מופעלות ברגעים הבאים:

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

במקרים כאלה, מומלץ להמשיך לספקי הזהויות הבאים, אם יש כאלה.
רגע נסגר: המצב הזה מתרחש כש-Google מאחזרת בהצלחה פרטי כניסה או כשמשתמש רוצה להפסיק את תהליך אחזור פרטי הכניסה. לדוגמה, כשהמשתמש מתחיל להזין את שם המשתמש והסיסמה שלו בתיבת הדו-שיח של הכניסה, אפשר להפעיל את השיטה google.accounts.id.cancel() כדי לסגור את ההנחיה 'הקשה אחת' ולהפעיל אירוע של סגירה של רגע.

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

בדוגמה הבאה מוטמע הרגע שהושמט:

<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()`	האם ההתראה הזו מתייחסת לרגעים שמוצגים ב-Google Photos? הערה: כש-FedCM מופעל, ההתראה הזו לא מופעלת. למידע נוסף, ראו הדף מעבר ל-FedCM.
`isDisplayed()`	האם ההתראה הזו מתייחסת לרגעים של הצגת תוכן, והממשק המשתמש מוצג? הערה: כש-FedCM מופעל, ההתראה הזו לא מופעלת. למידע נוסף, ראו הדף מעבר ל-FedCM.
`isNotDisplayed()`	האם ההתראה הזו מתייחסת לרגעים של הצגת תוכן, והממשק המשתמש לא מוצג? הערה: כש-FedCM מופעל, ההתראה הזו לא מופעלת. למידע נוסף, ראו הדף מעבר ל-FedCM.
`getNotDisplayedReason()`	הסיבה המפורטת לכך שממשק המשתמש לא מוצג. אלה הערכים האפשריים: `browser_not_supported` `invalid_client` `missing_client_id` `opt_out_or_no_session` `secure_http_required` `suppressed_by_user` `unregistered_origin` `unknown_reason` הערה: כש-FedCM מופעל, אי אפשר להשתמש בשיטה הזו. למידע נוסף, ראו הדף מעבר ל-FedCM.
`isSkippedMoment()`	האם ההתראה הזו מתייחסת לרגעים שדילוגתם עליהם?
`getSkippedReason()`	הסיבה המפורטת לרגע שדילגת עליו. אלה הערכים האפשריים: `auto_cancel` `user_cancel` `tap_outside` `issuing_failed` הערה: כש-FedCM מופעל, אי אפשר להשתמש בשיטה הזו. למידע נוסף, ראו הדף מעבר ל-FedCM.
`isDismissedMoment()`	האם ההתראה הזו מוצגת לרגע סגירה?
`getDismissedReason()`	הסיבה המפורטת לביטול. אלה הערכים האפשריים: `credential_returned` `cancel_called` `flow_restarted`
`getMomentType()`	החזרת מחרוזת של סוג הרגע. אלה הערכים האפשריים: `display` `skipped` `dismissed`

סוג הנתונים: CredentialResponse

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

שדה
`credential`	השדה הזה הוא טוקן המזהה שהוחזר.
`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 GSuite email address
  "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's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

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

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

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

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

הסמוי הסופי

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

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

שיטה: google.accounts.id.renderButton

השיטה 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`	עיצוב לחצן רגיל.
`filled_blue`	עיצוב לחצן עם מילוי כחול.
`filled_black`	עיצוב לחצן עם מילוי שחור.

size

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

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

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

גודל
`large`	לחצן גדול.
`medium`	לחצן בגודל בינוני.
`small`	לחצן קטן.

text

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

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

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

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

טקסט
`signin_with`	הטקסט של הלחצן הוא 'כניסה באמצעות חשבון Google'.
`signup_with`	טקסט הלחצן הוא 'הרשמה באמצעות חשבון Google'.
`continue_with`	טקסט הלחצן הוא 'המשך באמצעות חשבון Google'.
`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`	הלוגו של Google מיושר לשמאל.
`center`	הלוגו של Google ממורכז.

רוחב

הרוחב המינימלי של הלחצן, בפיקסלים. הרוחב המקסימלי הוא 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'.

הסמוי הסופי

אופציונלי: אפשר להקצות מחרוזת ייחודית לכל לחצן, כי אפשר להציג כמה לחצני כניסה באמצעות חשבון 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>

שיטה: google.accounts.id.storeCredential

ה-method הזה הוא מעטפת ל-method store() של ממשק ה-API המקורי של מנהל פרטי הכניסה בדפדפן. לכן, אפשר להשתמש בו רק כדי לאחסן פרטי כניסה מסוג סיסמה. דוגמה לקוד של השיטה:

google.accounts.id.storeCredential(Credential, callback)

הקוד לדוגמה הבא מיישם את ה-method google.accounts.id.storeCredential עם הפונקציה onSignIn():

<script>
  function onSignIn() {
    let cred = {id: '...', password: '...'};
    google.accounts.id.storeCredential(cred);
  }
</script>

שיטה: 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 = () => {
    ...
};

קריאת החזרה (callback) הזו היא רק קיצור דרך לקריאת החזרה 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.

בדוגמת הקוד הבאה מוצג איך משתמשים בשיטה revoke עם מזהה.

  google.accounts.id.revoke('1618033988749895', done => {
    console.log(done.error);
  });

סוג הנתונים: RevocationResponse

כשפונקציית callback מופעלת, אובייקט RevocationResponse מועבר כפרמטר. בטבלה הבאה מפורטים השדות שמכילים את אובייקט התגובה לביטול:

שדה
`successful`	השדה הזה הוא ערך ההחזרה של קריאת ה-method.
`error`	השדה הזה יכול להכיל הודעת תגובה מפורטת לשגיאה.

בוצעה בהצלחה

השדה הזה הוא ערך בוליאני שמוגדר כ-True אם הקריאה לשיטת הביטול הצליחה או False במקרה של כשל.

error

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