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

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

סטטוס הספרייה

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

עדכון שתומך בתאימות לאחור מוסיף לספריית הכניסה באמצעות חשבון Google את ממשקי ה-API של FedCM. רוב השינויים מתבצעים בצורה חלקה, אבל העדכון כולל הבדלים בהנחיות למשתמשים, ב-permissions-policy של iframe וב-Content Security Policy (CSP). השינויים האלה עשויים להשפיע על אפליקציית האינטרנט שלכם, וייתכן שתצטרכו לבצע שינויים בקוד האפליקציה ובהגדרות האתר.

במהלך תקופת המעבר, אפשרות תצורה קובעת אם נעשה שימוש בממשקי ה-API של FedCM במהלך הכניסה של המשתמשים לחשבון.

אחרי תקופת המעבר, ממשקי FedCM API יהיו חובה לכל אפליקציות האינטרנט שמשתמשות בספריית Google Sign-In.

ציר הזמן

עדכון אחרון: ספטמבר 2024

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

  • מרץ 2023 הוצאה משימוש של התמיכה בספרייה של פלטפורמת 'כניסה באמצעות חשבון Google'.
  • מתחיל תקופת המעבר של יולי 2024, ונוספת תמיכה בממשקי FedCM API בספריית הפלטפורמה של כניסה באמצעות חשבון Google. כברירת מחדל, Google קובעת את אחוז הבקשות של משתמשים לכניסה באמצעות FedCM במהלך התקופה הזו. אפליקציות אינטרנט יכולות לשנות את ההתנהגות הזו באופן מפורש באמצעות הפרמטר use_fedcm.
  • החל ממרץ 2025, חובה להשתמש ב-FedCM APIs בספריית הפלטפורמה של כניסה באמצעות חשבון Google. לאחר מכן, הפרמטר use_fedcm יתעלם וכל הבקשות לכניסת משתמשים ישתמשו ב-FedCM.

השלבים הבאים

יש שלוש אפשרויות לבחירה:

  1. מבצעים הערכת השפעה, ואם צריך, מעדכנים את אפליקציית האינטרנט. הגישה הזו מאפשרת לבדוק אם נעשה שימוש בתכונות שדורשות שינויים באפליקציית האינטרנט. ההוראות מפורטות בקטע הבא במדריך.
  2. עוברים אל הספרייה של Google Identity Services (GIS). מומלץ מאוד לעבור לספריית הכניסה העדכנית והנתמכת. כדי לעשות זאת, פועלים לפי ההוראות האלה.
  3. לא לעשות דבר. אפליקציית האינטרנט תתעדכן באופן אוטומטי כשספריית הכניסה לחשבון Google תועבר לממשקי FedCM API לכניסת משתמשים. זו האפשרות שתדרוש הכי פחות עבודה, אבל יש סיכון מסוים שהמשתמשים לא יוכלו להיכנס לאפליקציית האינטרנט.

ביצוע הערכת השפעה

יש לפעול לפי ההוראות הבאות כדי לקבוע אם אפשר לעדכן את אפליקציית האינטרנט בצורה חלקה באמצעות עדכון תואם לאחור, או אם יש צורך בשינויים כדי למנוע מהמשתמשים להיכנס לחשבון כשספריית הפלטפורמה של Google Sign-in תאמץ באופן מלא את ממשקי ה-API של FedCM.

הגדרה

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

לפני שממשיכים:

  • מעדכנים את Chrome למחשב לגרסה האחרונה. כדי לבדוק את Chrome ל-Android צריך את הגרסה M128 ואילך, ולא ניתן לבדוק אותו בגרסאות קודמות.

  • פותחים את chrome://flags ומגדירים את התכונות הבאות לערכים הבאים:

    • #fedcm-authz מופעל
    • #tracking-protection-3pcd מופעל
    • #third-party-cookie-deprecation-trial מושבת
    • #tpcd-metadata-grants מושבת
    • #tpcd-heuristics-grants מושבת

    ומפעילים מחדש את Chrome.

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

    • gapi.client.init({use_fedcm: true}), או
    • gapi.auth2.init({use_fedcm: true}), או
    • gapi.auth2.authorize({use_fedcm: true}).

  • ביטול התוקף של גרסאות ששמורות במטמון של ספריית הפלטפורמה לכניסה באמצעות חשבון Google. בדרך כלל אין צורך בשלב הזה, כי הגרסה האחרונה של הספרייה נשלחת ישירות לדפדפן על ידי הכללת api.js, ‏ client.js או platform.js בתג <script src> (הבקשה עשויה להשתמש בכל אחד משמות החבילות האלה לספרייה).

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

    1. פותחים את הדף Credentials (פרטי כניסה) של

    2. מוודאים שה-URI של האתר כלול במקורות מורשים של JavaScript. ה-URI כולל רק את הסכמה ואת שם המארח שמוגדר במלואו. לדוגמה, https://www.example.com.

    3. אפשר גם להחזיר את פרטי הכניסה באמצעות הפניה אוטומטית לנקודת קצה שאתם מארחים, במקום באמצעות קריאה חוזרת (callback) של JavaScript. במקרה כזה, צריך לוודא שה-URI להפניה האוטומטית נכללים בURI להפניה אוטומטית מורשים. מזהי URI להפניה אוטומטית כוללים את הסכימה, שם המארח המלא והנתיב, ועליהם לעמוד בכללי האימות של מזהי URI להפניה אוטומטית. לדוגמה: https://www.example.com/auth-receiver.

בדיקה

אחרי שמבצעים את ההוראות בקטע 'הגדרה':

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

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

  • ב-Chrome, פותחים את החלונית רשת של כלי הפיתוח וטוענים מחדש את הדף.
  • משתמשים בערכים בעמודות Domain ו-Name כדי לאתר את הבקשה לספרייה:
    • הדומיין הוא apis.google.com ו-
    • השם הוא api.js, client.js או platform.js. הערך הספציפי של Name תלוי בחבילת הספרייה שהמסמך ביקש.

לדוגמה, מסננים לפי apis.google.com בעמודה Domain ו-platform.js בעמודה Name.

בדיקת המדיניות בנושא הרשאות iframe

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

אחרי שמבצעים את ההוראות לאיתור הבקשה של ספריית הכניסה לחשבון Google, בוחרים את הבקשה של ספריית הכניסה לחשבון Google בחלונית Network (רשת) של DevTools ומאתרים את הכותרת Sec-Fetch-Site בקטע Request Headers (כותרות הבקשה) בכרטיסייה Headers (כותרות). אם הערך של הכותרת הוא:

  • same-site או same-origin, אז כללי מדיניות מקורות שונים לא חלים ואין צורך בשינויים.
  • יכול להיות שיהיה צורך לבצע שינויים ב-cross-origin אם נעשה שימוש ב-iframe.

כדי לוודא ש-iframe קיים:

  • בוחרים בחלונית Elements (רכיבים) ב-Chrome DevTools,
  • מקישים על Ctrl-F כדי למצוא iframe במסמך.

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

חוזרים על התהליך הזה לכל iframe במסמך. אפשר להטמיע iframes בתוך iframes אחרים, לכן חשוב להוסיף את הוראה ההרשאה לכל iframe הורה שמקיף את ה-iframe.

בדיקת מדיניות Content Security Policy

אם באתר שלכם נעשה שימוש במדיניות Content Security, יכול להיות שתצטרכו לעדכן את ה-CSP כדי לאפשר שימוש בספריית כניסה באמצעות Google.

אחרי שמבצעים את ההוראות לאיתור הבקשה של ספריית הכניסה לחשבון Google, בוחרים את הבקשה של ספריית הכניסה לחשבון Google בחלונית Network (רשת) של DevTools ומאתרים את הכותרת Content-Security-Policy בקטע Response Headers (כותרות התגובה) בכרטיסייה Headers (כותרות).

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

  • הוספת https://apis.google.com/js/, https://accounts.google.com/gsi/ ו-https://acounts.google.com/o/fedcm/ לכל הוראה מסוג connect-src,‏ default-src או frame-src.

  • מתבצעת הוספה של https://apis.google.com/js/bundle-name.js להנחיה script-src. מחליפים את bundle-name.js ב-api.js, ב-client.js או ב-platform.js, בהתאם לחבילת הספריות שהמסמך מבקש.

בדיקת שינויים בהנחיות של משתמשים

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

תמונה של תיבת הדו-שיח של FedCM

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

הפעלת משתמשים

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

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

כיום, אם המשתמש נכנס בעבר לאתר שלכם, תוכלו לקבל את פרטי הכניסה שלו בזמן האתחול של ספריית הכניסה לחשבון Google באמצעות gapi.auth2.init, בלי אינטראקציות נוספות עם המשתמש. לא ניתן לעשות זאת יותר, אלא אם המשתמש עבר לפחות פעם אחת את תהליך הכניסה ל-FedCM.

אם תבחרו להצטרף ל-FedCM ותפעילו את GoogleAuth.signIn, בפעם הבאה שאותו משתמש יבקר באתר שלכם, gapi.auth2.init יוכל לקבל את פרטי הכניסה של המשתמש במהלך האינטראקציה הראשונית ללא אינטראקציה של המשתמש.

תרחישים נפוצים לדוגמה

המסמכים למפתחים של ספריית Google Sign-In כוללים מדריכים ודוגמי קוד לתרחישי שימוש נפוצים. בקטע הזה נסביר איך FedCM משפיע על ההתנהגות שלהם.

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

    בהדגמה הזו, הלחצן <div> וכיתת המחלקה מעבדים את הלחצן, ולמשתמשים שכבר מחוברים לחשבון, האירוע onload בדף מחזיר פרטי כניסה של משתמש. נדרשת אינטראקציה של המשתמש כדי להיכנס לחשבון וליצור סשן חדש.

    האימפוליזציה של הספרייה מתבצעת על ידי המחלקה g-signin2 שמפעילה את gapi.load ואת gapi.auth2.init.

    תנועת משתמש, אירוע onclick של רכיב <div>, קורא ל-auth2.signIn במהלך הכניסה או ל-auth2.signOut ביציאה.

  • יצירת לחצן מותאם אישית לכניסה באמצעות חשבון Google

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

    האתחול של הספרייה מתבצע באמצעות אירוע onload לספרייה platform.js, והלחצן מוצג על ידי gapi.signin2.render.

    תנועת משתמש, לחיצה על לחצן הכניסה, גורמת לקריאה ל-auth2.signIn.

    בהדגמה השנייה, נעשה שימוש ברכיב <div>, בסגנונות CSS ובגרפיקה בהתאמה אישית כדי לשלוט במראה של לחצן הכניסה. נדרשת אינטראקציה של המשתמש כדי להיכנס לחשבון וליצור סשן חדש.

    האתחול של הספרייה מתבצע בזמן הטעינה של המסמך באמצעות פונקציית התחלה שמפעילה את gapi.load,‏ gapi.auth2.init ו-gapi.auth2.attachClickHandler.

    תנועת משתמש, אירוע onclick של רכיב <div>, קוראת ל-auth2.signIn באמצעות auth2.attachClickHandler במהלך הכניסה או auth2.signOut בזמן היציאה.

  • מעקב אחרי מצב הסשן של המשתמש

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

    אתחול הספרייה מתבצע ישירות על ידי קריאה ישירה ל-gapi.load, ל-gapi.auth2.init ול-gapi.auth2.attachClickHandler() אחרי ש-platform.js נטען באמצעות script src.

    תנועת משתמש, אירוע onclick של רכיב <div>, קורא ל-auth2.signIn באמצעות auth2.attachClickHandler במהלך הכניסה או auth2.signOut ביציאה.

  • בקשה להרשאות נוספות

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

    אתחול הספרייה מתבצע באמצעות האירוע onload בספרייה platform.js, באמצעות קריאה ל-gapi.signin2.render.

    תנועת משתמש, לחיצה על רכיב <button>, מפעילה בקשה להיקפי הרשאות נוספים של OAuth 2.0 באמצעות googleUser.grant או auth2.signOut בזמן היציאה מהחשבון.

  • שילוב של כניסה באמצעות חשבון Google באמצעות מאזינים

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

    אתחול הספרייה מתבצע כשהמסמך נטען באמצעות פונקציית התחלה, שקוראת ל-gapi.load, ל-gapi.auth2.init ול-gapi.auth2.attachClickHandler. לאחר מכן, משתמשים ב-auth2.isSignedIn.listen וב-auth2.currentUser.listen כדי להגדיר התראות על שינויים במצב הסשן. לבסוף, auth2.SignIn נקרא כדי להחזיר את פרטי הכניסה של משתמשים שנכנסו לחשבון.

    תנועת משתמש, אירוע onclick של רכיב <div>, קורא ל-auth2.signIn באמצעות auth2.attachClickHandler במהלך הכניסה או auth2.signOut ביציאה.

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

    בהדגמה הזו, תנועת משתמש משמשת לבקשת קוד אימות של OAuth 2.0, וקריאה חוזרת (callback) של JS מבצעת קריאה ל-AJAX כדי לשלוח את התשובה לשרת הקצה העורפי לצורך אימות.

    האתחול של הספרייה מתבצע באמצעות אירוע onload לספרייה platform.js, שמשתמש בפונקציית התחלה כדי לקרוא ל-gapi.load ול-gapi.auth2.init.

    תנועת משתמש, לחיצה על רכיב <button>, מפעילה בקשה לקוד הרשאה באמצעות קריאה ל-auth2.grantOfflineAccess.

  • SSO בפלטפורמות שונות

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

ניהול תקופת המעבר

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

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

הבעת הסכמה

כדאי לקבוע אם כל ניסיונות הכניסה לאתר שלכם, או חלק מהם, ישתמשו בממשקי API של FedCM. כדי לעשות זאת, מגדירים את use_fedcm לערך true כשמאתחלים את ספריית הפלטפורמה. במקרה הזה, בקשת הכניסה של המשתמש משתמשת ב-API של FedCM.

ביטול הצטרפות

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

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

עזרה

אפשר לחפש או לפרסם שאלות ב-StackOverflow באמצעות התג google-signin.