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

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

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

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

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>

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

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

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

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

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

שדה
client_id מזהה הלקוח של האפליקציה
auto_select הפעלת הבחירה האוטומטית.
callback פונקציית JavaScript שמטפלת באסימונים מזהים. Google One Tap וגם הלחצן 'כניסה באמצעות חשבון Google' popup מצב חוויית המשתמש: .
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.

client_id

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

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

auto_select

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

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

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

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

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

login_uri

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

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

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

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

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

סוג אופציונלי דוגמה
כתובת 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

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

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

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

ux_mode

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

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

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

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

allowed_parent_origin

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

intermediate_iframe_close_callback

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

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

סוג חובה דוגמה
פונקציה אופציונלי 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

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

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

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

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

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

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

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

    במקרים כאלה, מומלץ להמשיך לזהות הבאה ספקים, אם יש כאלה.

  • רגע שנסגר: מצב זה מתרחש כש-Google מאחזרת בהצלחה פרטי כניסה או שהמשתמש רוצה להפסיק את תהליך האחזור של פרטי הכניסה. עבור כשהמשתמש מתחיל להזין את שם המשתמש והסיסמה שלו בתיבת הדו-שיח לכניסה, אפשר לקרוא ל-method 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() האם ההתראה הזו היא לרגע הצגה?

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

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

select_by

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

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

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

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

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

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

ערך תיאור
auto כניסה אוטומטית של משתמש בסשן קיים שניתנה הסכמה לשיתוף פרטי הכניסה. חל רק על בדפדפנים שלא נתמכים ב-FedCM.
user משתמש עם סשן קיים שהסכים בעבר לחצת על 'המשך בתור' בהקשה אחת כדי לשתף פרטי כניסה. רלוונטי רק לדפדפנים שאינם נתמכים על ידי FedCM.
fedcm משתמש לחץ על הלחצן 'המשך בתור' בהקשה אחת לחצן לשיתוף באמצעות FedCM. רלוונטי רק ל-FedCM נתמך בדפדפנים אחרים.
fedcm_auto כניסה אוטומטית של משתמש בסשן קיים בעבר ניתנה הסכמה לשיתוף פרטי הכניסה באמצעות FedCM One Tap. רלוונטי רק ל-FedCM נתמך בדפדפנים אחרים.
user_1tap משתמש שיש לו סשן קיים לחץ על הלחצן 'המשך בתור' בהקשה אחת הלחצן כדי להביע הסכמה ולשתף פרטי כניסה. חל רק על Chrome v75 ואילך.
user_2tap משתמש ללא סשן קיים לחץ על הלחצן 'המשך בתור' בהקשה אחת כדי לבחור חשבון ולחצת על הלחצן 'אישור' חלון קופץ לאישור ולשיתוף פרטי הכניסה. חלה על בדפדפנים שלא מבוססים על Chromium.
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 בדפי האינטרנט שלך.

אפשר לראות דוגמה לקוד הבא של ה-method:

google.accounts.id.renderButton(
      /** @type{!HTMLElement} */ parent,
      /** @type{!GsiButtonConfiguration} */ options
    )

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

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

מאפיין
type סוג הלחצן: סמל או לחצן רגיל.
theme עיצוב הלחצנים. לדוגמה, fill_blue או fill_black.
size גודל הלחצן. לדוגמה: קטן או גדול.
text טקסט הלחצן. לדוגמה, 'כניסה באמצעות חשבון Google' או "Sign up with 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
לחצן קטן לחצן של סמל קטן
לחצן קטן.

טקסט

טקסט הלחצן. ערך ברירת המחדל הוא 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...")
  }

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

הסמוי הסופי

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

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

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

סוג הנתונים: פרטי כניסה

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

שדה
id מזהה את המשתמש.
password הסיסמה

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

כשהמשתמש יצא מהאתר, צריך להפעיל את השיטה google.accounts.id.disableAutoSelect כדי לתעד את הסטטוס בקובצי cookie. הזה מונעת מצב של 'לולאה בדויה' של UX. רואים את קטע הקוד הבא של ה-method:

google.accounts.id.disableAutoSelect()

דוגמת הקוד הבאה מטמיעה את הקוד google.accounts.id.disableAutoSelect עם הפונקציה onSignout():

<script>
  function onSignout() {
    google.accounts.id.disableAutoSelect();
  }
</script>

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

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

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

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

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

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

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

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. אין באופן שונה.

הקוד לדוגמה הבא מיישם קריאה חוזרת של onGoogleLibraryLoad:

<script>
  window.onGoogleLibraryLoad = () => {
   google.accounts.id.initialize({
     ...
   });
   google.accounts.id.prompt();
  };
</script>

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

ה-method google.accounts.id.revoke מבטלת את הענקת ה-OAuth ששימשה לשיתוף של אסימון מזהה של המשתמש שצוין. רואים את קטע הקוד הבא של ה-method: javascript google.accounts.id.revoke(login_hint, callback)

פרמטר סוג תיאור
login_hint מחרוזת כתובת האימייל או המזהה הייחודי של חשבון Google של המשתמש. המזהה הוא המאפיין sub של מטען ייעודי (payload) של פרטי כניסה.
callback פונקציה handler אופציונלי של RevocationResponse.

דוגמת הקוד הבאה מראה איך משתמשים ב-method revoke עם מזהה. 

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

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

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

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

הפעולה בוצעה

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

error

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