تسجيل الدخول على أجهزة التلفزيون والأجهزة ذات الإدخال المحدود

يمكنك السماح للمستخدمين بتسجيل الدخول إلى تطبيقك باستخدام حساباتهم على Google على الأجهزة ذات إمكانات الإدخال المحدودة، مثل أجهزة التلفزيون المتّصلة بالإنترنت.

يعرض التطبيق رمزًا قصيرًا وعنوان URL لتسجيل الدخول للمستخدم. بعد ذلك، يفتح المستخدِم عنوان URL لصفحة تسجيل الدخول في متصفّح ويب ويُدخل الرمز ويمنح التطبيق إذنًا بالوصول إلى معلومات تسجيل الدخول الخاصة بالمستخدم. أخيرًا، يتلقى التطبيق رسالة تأكيد ويتم تسجيل دخول المستخدم

لاستخدام عملية تسجيل الدخول هذه، يجب أن يعمل التطبيق على جهاز يستوفي المعايير التالية:

  • يجب أن يكون الجهاز قادرًا على عرض عنوان URL من 40 حرفًا ورمز مستخدم من 15 حرفًا، إلى جانب تعليمات إلى المستخدم.
  • يجب أن يكون الجهاز متصلاً بالإنترنت.

الحصول على معرِّف العميل وسر العميل

يحتاج تطبيقك إلى معرِّف عميل OAuth 2.0 وسر عميل لإرسال الطلبات إلى نقاط نهاية تسجيل الدخول إلى Google.

للبحث عن مُعرّف العميل وسر العميل لمشروعك، يمكنك إجراء ما يلي:

  1. اختَر أحد بيانات اعتماد OAuth 2.0 الحالية أو افتح صفحة بيانات الاعتماد.
  2. أنشِئ بيانات اعتماد OAuth 2.0 لمشروعك من خلال النقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth، إذا لم يسبق لك إجراء ذلك، وتقديم المعلومات اللازمة لإنشاء بيانات الاعتماد.
  3. ابحث عن معرِّف العميل في قسم معرِّفات عميل OAuth 2.0. لمعرفة التفاصيل، انقر على معرِّف العميل.

إذا كنت بصدد إنشاء معرِّف عميل جديد، اختَر نوع التطبيق أجهزة التلفزيون وأجهزة الإدخال المحدودة.

الحصول على رمز المستخدم وعنوان URL للتحقق

بعد أن يطلب أحد المستخدمين تسجيل الدخول باستخدام حساب Google، يمكنك الحصول على رمز المستخدم وعنوان URL للتحقق من خلال إرسال طلب HTTP POST إلى نقطة نهاية جهاز OAuth 2.0، https://oauth2.googleapis.com/device/code. قم بتضمين معرف العميل الخاص بك وقائمة بالنطاقات التي تحتاجها مع الطلب. وإذا كنت تريد فقط تسجيل دخول المستخدمين باستخدام حساباتهم على Google، اطلب النطاقَين profile وemail فقط، أو إذا كنت تريد طلب إذن لطلب واجهة برمجة تطبيقات متوافقة نيابةً عن المستخدمين، يمكنك طلب النطاقات المطلوبة بالإضافة إلى النطاقَين profile وemail.

في ما يلي مثال على طلب لرمز مستخدم:

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

client_id=YOUR_GOOGLE_CLIENT_ID&scope=email%20profile

باستخدام curl:

curl -d "client_id=YOUR_GOOGLE_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 للتحقق من نقطة نهاية الجهاز، اعرضهما ووجِّه المستخدم إلى فتح عنوان URL وإدخال رمز المستخدم.

إنّ قيمتَي verification_url وuser_code عرضة للتغيير. صمم واجهة المستخدم بطريقة يمكنها التعامل مع الحدود التالية:

  • يجب عرض user_code في حقل عريض بما يكفي للتعامل مع 15 حرفًا بحجم W.
  • يجب عرض verification_url في حقل عريض بما فيه الكفاية للتعامل مع سلسلة عنوان URL طولها 40 حرفًا.

يمكن أن تحتوي كلتا السلسلتين على أي حرف قابل للطباعة من مجموعة أحرف US-ASCII.

عند عرض سلسلة user_code، يجب عدم تعديل السلسلة بأي طريقة (مثل تغيير الحالة أو إدراج أحرف تنسيق أخرى)، لأنّ تطبيقك قد يتعطّل إذا تغيّر تنسيق الرمز في المستقبل.

يمكنك تعديل سلسلة verification_url من خلال إزالة المخطط من عنوان URL لأغراض العرض إن أردت. فإذا فعلت ذلك، فتأكد من أن تطبيقك يمكنه التعامل مع صيغتي "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=YOUR_GOOGLE_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

باستخدام curl:

curl -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_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 التي سمح بها المستخدم.

إنّ صلاحية أرقام التعريف ورموز الدخول محدودة. للحفاظ على تسجيل دخول المستخدم بعد فترة استخدام الرموز المميّزة، يمكنك تخزين الرمز المميّز لإعادة التحميل واستخدامه في طلب رموز مميّزة جديدة.

الحصول على معلومات الملف الشخصي للمستخدم من الرمز المميز للمعرّف

يمكنك الحصول على معلومات الملف الشخصي للمستخدم الذي سجَّل الدخول عن طريق فك ترميز الرمز المميّز للمعرّف باستخدام أي مكتبة لفك ترميز JWT. على سبيل المثال، باستخدام مكتبة JavaScript jwt-decode Auth0:

var user_profile = jwt_decode(<var>id_token</var>);

// 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"];

مزيد من المعلومات

  • لإبقاء المستخدمين في وضع تسجيل الدخول بعد انتهاء مدة صلاحية الرمز المميّز للمعرّف، يُرجى الاطّلاع على إعادة تحميل رمز دخول.
  • إذا كنت بحاجة إلى المصادقة باستخدام خادم خلفية، يمكنك الاطّلاع على المصادقة باستخدام خادم خلفية للحصول على معلومات حول إجراء ذلك بأمان.