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

כניסה באמצעות טלוויזיות והתקני קלט מוגבלים

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

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

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

  • במכשיר צריכה להיות אפשרות להציג כתובת URL באורך של 40 תווים וקוד משתמש בן 15 תווים, לצד הוראות למשתמש.
  • המכשיר חייב להיות מחובר לאינטרנט.

קבלת מזהה לקוח וסוד לקוח

האפליקציה שלך צריכה מזהה לקוח ב-OAuth 2.0 וסוד לקוח כדי לשלוח בקשות לנקודות קצה (endpoint) של Google.

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

  1. יש לבחור פרטי כניסה קיימים מסוג OAuth 2.0 או לפתוח את דף פרטי הכניסה.
  2. אם עדיין לא עשית זאת, עליך ליצור פרטי כניסה של OAuth 2.0 לפרויקט שלך. לשם כך, יש ללחוץ על יצירת פרטי כניסה > מזהה לקוח OAuth ולספק את המידע הנדרש ליצירת פרטי הכניסה.
  3. מחפשים את Client ID בקטע Client-ID 2.0 Clients. לפרטים, לוחצים על מספר הלקוח.

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

קבלת קוד משתמש וכתובת URL לאימות

אחרי שמשתמש מבקש להיכנס באמצעות חשבון Google, יש לך אפשרות להשיג קוד משתמש וכתובת URL לאימות, על ידי שליחת בקשת HTTP POST לנקודת הקצה מסוג OAuth 2.0, https://oauth2.googleapis.com/device/code. יש לכלול את מזהה הלקוח ורשימה של היקפי ההרשאות הנדרשים בבקשה. אם ברצונך להיכנס למשתמשים רק עם חשבונות Google שלהם, יש לבקש רק את ההיקפים profile ו-email. לחלופין, אם ברצונך לבקש הרשאה לקרוא ל-API נתמך עבור משתמשים, עליך לבקש את ההיקפים הנדרשים בנוסף להיקפי ההרשאות של profile ושל email.

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

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID&scope=email%20profile

באמצעות curl:

curl -d "client_id=CLIENT_ID&scope=email profile" https://oauth2.googleapis.com/device/code

התגובה מוחזרת כאובייקט JSON:

{
  "device_code" : "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code" : "GQVQ-JKEC",
  "verification_url" : "https://www.google.com/device",
  "expires_in" : 1800,
  "interval" : 5
}

האפליקציה שלך מציגה את הערכים user_code ו-verification_url למשתמש, ובה בעת ממלאת את נקודת הקצה לכניסה ב-interval, עד שהמשתמש נכנס או עד למועד שצוין על ידי expires_in.

להציג את קוד המשתמש ואת כתובת האתר לאימות

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

הערכים verification_url ו-user_code עשויים להשתנות. מעצבים את ממשק המשתמש באופן שיאפשר את המגבלות הבאות:

  • השדה user_code חייב להופיע בשדה רחב מספיק כדי לטפל ב-15 תווים בגודל W.
  • יש להציג את verification_url בשדה רחב מספיק כדי לטפל במחרוזת כתובת URL באורך של 40 תווים.

שתי המחרוזות יכולות להכיל כל תו להדפסה מתוך קבוצת התווים US-ASCII.

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

אפשר לשנות את המחרוזת ב-verification_url על ידי הסרת הסכימה מכתובת ה-URL למטרות תצוגה. אם תעשו זאת, חשוב לוודא שהאפליקציה יכולה לטפל גם בווריאציות {0} "http" וגם "https" אין לשנות את המחרוזת verification_url.

כשהמשתמש מנווט לכתובת ה-URL לאימות, הוא רואה דף דומה לזה:

חיבור מכשיר על ידי הזנת קוד

אחרי שהמשתמש מזין את קוד המשתמש, באתר הכניסה של Google מוצג מסך הסכמה כמו זה:

דוגמה למסך הסכמה ללקוח במכשיר

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

קבלת אסימון מזהה ורענון האסימון

אחרי שהאפליקציה תציג את קוד המשתמש וכתובת ה-URL לאימות, מתחילים לערוך סקר לגבי נקודת הקצה של האסימון (https://oauth2.googleapis.com/token) עם קוד המכשיר שקיבלת מנקודת הקצה של המכשיר. סקר את נקודת הקצה של האסימון במרווח בשניות, שצוין בערך interval.

לפניכם בקשה לדוגמה:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

באמצעות curl:

curl -d "client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0" https://oauth2.googleapis.com/token

אם המשתמש עדיין לא אישר את הבקשה, התגובה תהיה כך:

{
  "error" : "authorization_pending"
}

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

{
  "error" : "slow_down"
}

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

{
  "access_token" : "ya29.AHES6ZSuY8f6WFLswSv0HZLP2J4cCvFSj-8GiZM0Pr6cgXU",
  "token_type" : "Bearer",
  "expires_in" : 3600,
  "refresh_token" : "1/551G1yXUqgkDGnkfFk6ZbjMMMDIMxo3JFc8lY8CAR-Q",
  "id_token": "eyJhbGciOiJSUzI..."
}

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

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

קבלת מידע על פרופיל המשתמש באסימון המזהה

אפשר לקבל פרטי פרופיל לגבי המשתמש שמחובר לחשבון על ידי פענוח המזהה עם כל ספריית פענוח של JWT. לדוגמה, השתמשו בספריית JavaScript 0wt-decode ב-JavaScript:

var user_profile = jwt_decode(id_token);

// The "sub" field is available on all ID tokens. This value is unique for each
// Google account and can be used to identify the user. (But do not send this
// value to your server; instead, send the whole ID token so its authenticity
// can be verified.)
var user_id = user_profile["sub"];

// These values are available when you request the "profile" and "email" scopes.
var user_email = user_profile["email"];
var email_verified = user_profile["email_verified"];
var user_name = user_profile["name"];
var user_photo_url = user_profile["picture"];
var user_given_name = user_profile["given_name"];
var user_family_name = user_profile["family_name"];
var user_locale = user_profile["locale"];
.

מידע נוסף