במדריך הזה נסביר על השימוש בממשקי FedCM API בספריית הפלטפורמה של כניסה באמצעות חשבון Google. הנושאים כוללים את ציר הזמן ואת השלבים הבאים לעדכון תואם לאחור של הספרייה, הוראות לביצוע הערכת השפעה ולאימות שהכניסה של המשתמשים ממשיכה לפעול כצפוי, ואם יש צורך, הוראות לעדכון אפליקציית האינטרנט. בנוסף, מוסבר איך לנהל את תקופת המעבר ואיך לקבל עזרה.
סטטוס הספרייה
אפליקציות אינטרנט חדשות לא יכולות להשתמש בספרייה של פלטפורמת הכניסה לחשבון Google שהוצאה משימוש, אבל אפליקציות שכבר משתמשות בספרייה הזו יכולות להמשיך לעשות זאת עד להודעה חדשה. לא נקבע תאריך סגירה סופי לספרייה. מידע נוסף זמין במאמר הוצאה משימוש של תמיכה והוצאה משימוש.
עדכון שתומך בתאימות לאחור מוסיף לספריית הכניסה באמצעות חשבון Google את ממשקי ה-API של FedCM. רוב השינויים מתבצעים בצורה חלקה, אבל יש הבדלים בין הגרסה הקודמת לעדכון בהנחיות למשתמשים, ב-permissions-policy של iframe ובמדיניות אבטחת התוכן (CSP). השינויים האלה עשויים להשפיע על אפליקציית האינטרנט שלכם, וייתכן שתצטרכו לבצע שינויים בקוד האפליקציה ובהגדרות האתר.
במהלך תקופת המעבר, אפשרות תצורה קובעת אם נעשה שימוש בממשקי ה-API של FedCM במהלך הכניסה של המשתמשים לחשבון.
אחרי תקופת המעבר, ממשקי FedCM API יהיו חובה לכל אפליקציות האינטרנט שמשתמשות בספריית Google Sign-In.
ציר הזמן
עדכון אחרון: ספטמבר 2024
אלה התאריכים והשינויים שמשפיעים על התנהגות הכניסה של המשתמשים:
- מרץ 2023 הוצאה משימוש של התמיכה בספריית הפלטפורמה של כניסה באמצעות חשבון Google.
- מתחיל תקופת המעבר של יולי 2024, ונוספת תמיכה בספריית הפלטפורמה של כניסה באמצעות חשבון Google בממשקי FedCM API. כברירת מחדל, Google קובעת את אחוז הבקשות של משתמשים לכניסה באמצעות FedCM במהלך התקופה הזו. אפליקציות אינטרנט יכולות לשנות את ההתנהגות הזו באופן מפורש באמצעות הפרמטר
use_fedcm
. - החל ממרץ 2025, חובה להשתמש בממשקי ה-API של FedCM בספריית הפלטפורמה של 'כניסה באמצעות חשבון Google'. לאחר מכן, הפרמטר
use_fedcm
יתעלם וכל הבקשות של משתמשים לכניסה ישתמשו ב-FedCM.
השלבים הבאים
יש שלוש אפשרויות:
- מבצעים הערכת השפעה, ואם צריך, מעדכנים את אפליקציית האינטרנט. הגישה הזו מאפשרת לבדוק אם נעשה שימוש בתכונות שדורשות שינויים באפליקציית האינטרנט. ההוראות מפורטות בקטע הבא במדריך.
- מעבר ל ספריית Google Identity Services (GIS). מומלץ מאוד לעבור לספריית הכניסה העדכנית והנתמכת. כדי לעשות זאת, פועלים לפי ההוראות האלה.
- לא לעשות דבר. אפליקציית האינטרנט תתעדכן באופן אוטומטי כשספריית הכניסה לחשבון Google תועבר לממשקי FedCM API לכניסת משתמשים. זו האפשרות שמצריכה את המאמץ הקטן ביותר, אבל יש סיכון מסוים שהמשתמשים לא יוכלו להיכנס לאפליקציית האינטרנט.
ביצוע הערכת השפעה
יש לפעול לפי ההוראות הבאות כדי לקבוע אם אפשר לעדכן את אפליקציית האינטרנט בצורה חלקה באמצעות עדכון תואם לאחור, או אם יש צורך בשינויים כדי למנוע מהמשתמשים להיכנס לחשבון כשספריית הפלטפורמה של Google Sign-in תאמץ באופן מלא את ממשקי ה-API של FedCM.
הגדרה
כדי להשתמש ב-FedCM במהלך הכניסה של המשתמשים, נדרשים ממשקי API לדפדפן והגרסה האחרונה של ספריית הפלטפורמה לכניסה באמצעות חשבון Google.
לפני שממשיכים:
- מעדכנים את Chrome למחשב לגרסה האחרונה. כדי לבדוק את Chrome ל-Android צריך את הגרסה M128 ואילך, ולא ניתן לבדוק אותו בגרסאות קודמות.
- מגדירים את
use_fedcm
לערךtrue
כשמאתחלים את הספרייה של פלטפורמת הכניסה באמצעות חשבון Google באפליקציית האינטרנט. בדרך כלל, האיפוס נראה כך: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:
- פותחים את הדף Credentials (פרטי כניסה) של
מוודאים שה-URI של האתר נכלל במקורות JavaScript מורשים. ה-URI כולל רק את הסכימה ואת שם המארח המלא. לדוגמה,
https://www.example.com
.אפשר גם להחזיר את פרטי הכניסה באמצעות הפניה אוטומטית לנקודת קצה שאתם מארחים, במקום באמצעות קריאה חוזרת (callback) של JavaScript. במקרה כזה, צריך לוודא שה-URI להפניה האוטומטית נכללים בURI להפניה אוטומטית מורשים. מזהי URI להפניה אוטומטית כוללים את הסכימה, שם המארח המלא והנתיב, ועליהם לעמוד בכללי האימות של מזהי URI להפניה אוטומטית. לדוגמה:
https://www.example.com/auth-receiver
.
בדיקה
אחרי שמבצעים את ההוראות בקטע 'הגדרה':
- סוגרים את כל החלונות הפרטיים הקיימים ב-Chrome ופותחים חלון פרטי חדש. הפעולה הזו תמחק את כל התוכן או קובצי ה-cookie שנשמרו במטמון.
- טוענים את דף הכניסה של המשתמש ומנסים להיכנס.
כדי לזהות ולפתור בעיות מוכרות, פועלים לפי ההוראות שבקטעים הבאים במדריך:
מחפשים שגיאות או אזהרות במסוף שקשורות לספרייה של Google Sign-in.
חוזרים על התהליך הזה עד שלא מתקבלות שגיאות ואפשר להיכנס לחשבון. כדי לוודא שההתחברות בוצעה בהצלחה, צריך לוודא ש
BasicProfile.getEmail()
מחזירה את כתובת האימייל שלכם ושGoogleUser.isSignedIn()
היאTrue
.
איתור הבקשה לספרייה של כניסה באמצעות חשבון 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. במקרה כזה:
- מוסיפים את מדיניות ההרשאות
allow="identity-credentials-get"
ל-iframe ההורה.
חוזרים על התהליך הזה לכל iframe במסמך. אפשר להטמיע iframes בתוך iframes אחרים, לכן חשוב להוסיף את הוראה ההרשאה לכל iframe הורה שמקיף את ה-iframe.
בדיקת מדיניות Content Security Policy
אם באתר שלכם מוגדרת מדיניות אבטחת תוכן, יכול להיות שתצטרכו לעדכן את ה-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, הדפדפן מציג בקשה לקבלת הסכמה מהמשתמשים במקרים הבאים:
- משתמש נכנס בפעם הראשונה לאפליקציית אינטרנט באמצעות מכונה חדשה של דפדפן, או
- מתבצעת קריאה ל-
GoogleAuth.signIn
.
כיום, אם המשתמש נכנס בעבר לאתר שלכם, תוכלו לקבל את פרטי הכניסה שלו כשאתם מאתחלים את הספרייה של Google Sign-In באמצעות 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
.-
ב-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.