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

يمكنك السماح للمستخدمين بتسجيل الدخول إلى تطبيقك باستخدام حساباتهم على 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 لإثبات الملكية من خلال إرسال طلب POST عبر بروتوكول HTTP إلى نقطة نهاية 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 الخاصة بمنصّة Auth0 jwt-decode:

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

ملاحظة: بما أنّك تلقّيت الرمز المميّز للمعرّف مباشرةً من Google، يمكنك فك ترميزه بدون التحقّق منه. عندما تتلقّى رمز تعريف من مصدر غير Google، مثل تطبيق العميل إلى خادم الخلفية، عليك التحقّق من صحة الرمز لضمان أصالةه. راجِع مقالة المصادقة باستخدام ملف شخصي في أحد الخوادم الخلفية.

ملاحظة مهمة: استخدِم حقل sub فقط كمعرّف للمستخدم لأنّه فريد بين جميع حسابات Google ولا تتم إعادة استخدامه أبدًا. لا تستخدم عنوان البريد الإلكتروني كمعرّف لأنّ حساب Google يمكن أن يتضمّن عناوين بريد إلكتروني متعددة في أوقات مختلفة.

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

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