نقل البيانات من ميزة "تسجيل الدخول بحساب Google"

يساعدك هذا الدليل في فهم التغييرات والخطوات اللازمة لنقل مكتبات JavaScript بنجاح من مكتبة منصة "تسجيل الدخول بحساب Google" السابقة إلى مكتبة خدمات Google Identity الجديدة للمصادقة.

إذا كان البرنامج يستخدم مكتبة برامج Google API للغة JavaScript أو مكتبات أخرى سابقة للتفويض، يُرجى الاطّلاع على المقالة نقل البيانات إلى خدمات هوية Google للاطّلاع على مزيد من المعلومات.

المصادقة والترخيص

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

مثل مكتبة منصة "تسجيل الدخول بحساب Google" السابقة، تم تصميم مكتبة خدمات هوية Google الجديدة لإتاحة كل من عمليات المصادقة والترخيص.

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

إذا كانت حالة الاستخدام تتعلق بالمصادقة فقط، استمر في قراءة هذه الصفحة.

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

التغييرات التي أُجريت

بالنسبة إلى المستخدمين، توفّر مكتبة Google Identity Services الجديدة العديد من التحسينات على سهولة الاستخدام. تتضمن أهم التفاصيل ما يلي:

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

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

• الخيار لإضافة معلومات تسجيل دخول المستخدم إلى المحتوى الثابت في موقعك باستخدام HTML فقط،
• فصل مصادقة تسجيل الدخول عن التفويض ومشاركة بيانات المستخدمين، لم يعد من الضروري أن يتم تسجيل دخول المستخدمين إلى موقعك الإلكتروني من خلال تعقيد عملية دمج OAuth 2.0،
• سيظل كل من وضعي النافذة المنبثقة وإعادة التوجيه مدعومين، ولكن البنية الأساسية لبروتوكول OAuth 2.0 من Google الآن تعيد التوجيه إلى نقطة نهاية تسجيل الدخول إلى خادم الخلفية،
• الدمج بين الإمكانات المتوفرة في كل من مكتبات JavaScript API السابقة في Google Identity وGoogle API في مكتبة واحدة جديدة
• لردود تسجيل الدخول، يمكنك الآن تحديد ما إذا كنت تريد استخدام العد وتمت إزالة التوجيه من خلال دوال نمط getter للتبسيط أم لا.

مثال لنقل بيانات تسجيل الدخول

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

المكتبات والتكوين

إنّ مكتبة "تسجيل الدخول بحساب Google" السابقة: apis.google.com/js/platform.js ومكتبة برامج Google APIs للغة JavaScript: gapi.client لم تعُد مطلوبة لمصادقة المستخدم وتفويضه. وقد تم استبدالها بمكتبة JavaScript واحدة جديدة لخدمة Google Identity Services: accounts.google.com/gsi/client.

إنّ وحدات JavaScript الثلاث السابقة: api وclient وplatform المُستخدَمة لتسجيل الدخول يتم تحميلها من apis.google.com. لمساعدتك في تحديد المواقع الجغرافية التي قد يتم فيها تضمين المكتبة السابقة في موقعك الإلكتروني، عليك عادةً إجراء ما يلي:

• سيحمّل زر تسجيل الدخول التلقائي apis.google.com/js/platform.js،
• تحميل رسم زر مخصص apis.google.com/js/api:client.js،
• الاستخدام المباشر لـ gapi.client لتحميل apis.google.com/js/api.js

في معظم الحالات، يمكنك متابعة استخدام بيانات اعتماد Client ID الحالية لتطبيق الويب. كجزء من عملية نقل البيانات، ننصحك بمراجعة سياسات OAuth 2.0 واستخدام وحدة تحكُّم Google API للتأكيد وتعديل إعدادات البرنامج التالية إذا لزم الأمر:

• تستخدم تطبيقات الاختبار والإنتاج مشاريع منفصلة ويكون لها أرقام تعريف العملاء الخاصة بها،
• يكون نوع معرّف عميل OAuth 2.0 هو "تطبيق ويب"،
• يتم استخدام HTTPS لمصادر JavaScript المسموح بها ومعرِّفات الموارد المنتظمة (URI) لإعادة التوجيه.

تحديد الرمز المتأثر وإجراء الاختبار

ويمكن لملف تعريف الارتباط لتصحيح الأخطاء المساعدة في تحديد مكان الرمز المتأثر واختبار سلوك ما بعد الإيقاف النهائي.

في التطبيقات الكبيرة أو المعقّدة، قد يصعب العثور على جميع الرموز المتأثرة بإيقاف وحدة gapi.auth2 نهائيًا. لتسجيل الاستخدام الحالي للإمكانات التي سيتم إيقافها نهائيًا قريبًا لوحدة التحكم، اضبط قيمة ملف تعريف الارتباط G_AUTH2_MIGRATION على informational. اختياريًا، أضف نقطتَين متبوعتَين بقيمة مفتاح لتسجيل الدخول أيضًا إلى مساحة تخزين الجلسة. بعد تسجيل الدخول واستلام بيانات الاعتماد، قم بمراجعة السجلات التي تم جمعها أو إرسالها إلى الخلفية لتحليلها لاحقًا. على سبيل المثال، يحفظ informational:showauth2use المصدر وعنوان URL في مفتاح تخزين جلسة يُسمى showauth2use.

للتحقّق من سلوك التطبيق عند إيقاف تحميل الوحدة gapi.auth2، اضبط قيمة ملف تعريف الارتباط G_AUTH2_MIGRATION على enforced. ويتيح ذلك اختبار سلوك ما بعد الإيقاف قبل تاريخ التنفيذ.

القيم المحتملة لملفات تعريف الارتباط G_AUTH2_MIGRATION:

• enforced لا تحمِّل وحدة gapi.auth2.
• informational تسجيل استخدام الإمكانات المتوقّفة نهائيًا في وحدة تحكّم JavaScript. ويمكنك أيضًا تسجيل الدخول إلى مساحة تخزين الجلسة عند ضبط اسم مفتاح اختياري: informational:key-name.

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

HTML وJavaScript

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

إن الطريقة السابقة

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

الطريقة الجديدة

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

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

في هذا المثال المخصّص للمصادقة فقط، تحلّ مكتبة accounts.google.com/gsi/client الجديدة والفئة g_id_signin والكائن g_id_onload محلّ مكتبة apis.google.com/js/platform.js السابقة والكائن g-signin2.

بالإضافة إلى عرض الزر المخصص الجديد، يعرض الرمز النموذجي أيضًا النافذة المنبثقة الجديدة One Tap. أينما تعرض الزر المخصص، ننصحك بشدة بأن تعرض أيضًا النافذة المنبثقة "نقرة واحدة" لتقليل الصعوبات التي يواجهها المستخدم أثناء عملية الاشتراك وتسجيل الدخول.

على الرغم من أنّه لا يُنصح باستخدام هذا الزر بسبب زيادة الصعوبات في عملية تسجيل الدخول، يمكن عرض الزر المخصّص الجديد وحده بدون عرض مربّع الحوار "نقرة واحدة" في آنٍ واحد. ولإجراء ذلك، اضبط السمة data-auto_prompt على false.

واجهات برمجة التطبيقات HTML وJavaScript

يوضّح المثال السابق كيفية استخدام واجهة برمجة تطبيقات HTML الجديدة لإضافة معلومات تسجيل الدخول إلى موقعك الإلكتروني. بدلاً من ذلك، يمكنك استخدام واجهة برمجة تطبيقات JavaScript المكافئة وظيفيًا، أو مزج واجهات برمجة تطبيقات HTML وJavaScript ومطابقتها في موقعك الإلكتروني.

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

تسجيل الدخول من أي صفحة بنقرة واحدة

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

لتفعيل تسجيل الدخول من أي صفحة، ننصحك بتضمين g_id_onload في رأس أو تذييل أو عنصر آخر مشترك مضمّن في موقعك الإلكتروني بالكامل.

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

استجابة الرمز المميّز

لم يعد تسجيل دخول المستخدم يتطلب منك فهم رموز تفويض OAuth 2.0 أو رموز الدخول أو رموز إعادة التحميل أو التعامل مع هذه الرموز. بدلاً من ذلك، يتم استخدام رمز JSON المميّز للويب (JWT) لمشاركة حالة تسجيل الدخول والملف الشخصي للمستخدم. لمزيد من التبسيط، لم تعد مطالبًا باستخدام طرق موصل نمط "getter" للعمل مع بيانات الملف الشخصي للمستخدم.

يتم عرض بيانات اعتماد الرمز المميز لمعرّف JWT موقَّعًا من Google إما:

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

في كلتا الحالتين، عليك تعديل معالجات معاودة الاتصال الحالية عن طريق إزالة ما يلي:

• مكالمات صادرة إلى googleUser.getBasicProfile()،
• الإشارات إلى BasicProfile، والمكالمات المرتبطة بها لطرق getId() وgetName() وgetGivenName() وgetFamilyName() وgetImageUrl() وgetEmail()
• استخدام الكائن AuthResponse.

بدلاً من ذلك، استخدِم الإشارات المباشرة إلى الحقول الفرعية credential في كائن JWT CredentialResponse الجديد للتعامل مع بيانات الملف الشخصي للمستخدم.

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

لفهم كيفية تفاعل المستخدمين مع موقعك الإلكتروني بشكل أفضل، يمكن استخدام الحقل select_by في CredentialResponse لتحديد نتيجة موافقة المستخدم وعملية تسجيل الدخول المحدَّدة.

موافقة المستخدم وإبطال الإذن

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

يمكن للمستخدمين إبطال الأذونات وإلغاء ربط تطبيقك بحساباتهم على Google من خلال الانتقال إلى https://myaccount.google.com/permissions. بدلاً من ذلك، قد ينقطع الاتصال بتطبيقك مباشرةً من خلال تشغيل طلب بيانات من واجهة برمجة التطبيقات الذي تنفذه. وقد تم استبدال طريقة disconnect السابقة بطريقة revoke الأحدث.

عندما يحذف مستخدم حسابه على منصتك، من أفضل الممارسات استخدام revoke لإلغاء ربط تطبيقك بحسابه على Google.

كان من الممكن استخدام auth2.signOut() في السابق للمساعدة في إدارة تسجيل خروج المستخدمين من تطبيقك. يجب إزالة أي استخدام لـ auth2.signOut()، ويجب أن يدير تطبيقك مباشرةً حالة جلسة المستخدم وحالة تسجيل الدخول.

حالة الجلسة وأدوات الاستماع

لن تحتفظ المكتبة الجديدة بحالة تسجيل الدخول أو حالة الجلسة لتطبيق الويب.

يمثِّل كلٌّ من حالة تسجيل الدخول إلى حساب Google وحالة الجلسة في تطبيقك وحالة تسجيل الدخول مفهومان منفصلان ومنفصلان.

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

عند تضمين ميزة "تسجيل الدخول باستخدام حساب Google"، أو ميزة "نقرة واحدة" أو "تسجيل الدخول تلقائيًا" في موقعك الإلكتروني، يجب على مستخدمي موقعك الإلكتروني تسجيل الدخول أولاً إلى حساباتهم على Google لتنفيذ ما يلي:

• تقديم الموافقة على مشاركة الملف الشخصي للمستخدم عند الاشتراك لأول مرة أو تسجيل الدخول إلى موقعك،
• ولاحقًا لتسجيل الدخول عند تكرار الزيارات إلى موقعك الإلكتروني

يمكن أن يظل المستخدمون في وضع تسجيل الدخول أو تسجيل الخروج أو التبديل إلى حساب آخر على Google مع الحفاظ على جلسة نشطة على موقعك الإلكتروني.

أنت الآن مسؤول عن إدارة حالة تسجيل الدخول مباشرةً لمستخدمي تطبيق الويب الخاص بك. وقد ساعدك "تسجيل الدخول بحساب Google" سابقًا من خلال مراقبة حالة جلسة المستخدم.

أزل أي إشارات إلى auth2.attachClickHandler() ومعالجات معاودة الاتصال المسجَّلة فيه.

في السابق، كان يتم استخدام أجهزة الاستماع لمشاركة التغييرات في حالة تسجيل الدخول لحساب مستخدم على Google. لم تعُد أدوات الاستماع متاحة.

يُرجى إزالة أي إشارات إلى listen() وauth2.currentUser و auth2.isSignedIn.

بسكويت

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

لم يعُد ملف تعريف الارتباط G_ENABLED_IDPS الذي تم ضبطه في الإصدار السابق من مكتبة تسجيل الدخول بحساب Google مستخدَمًا بعد الآن.

قد تضبط مكتبة Google Identity Services الجديدة بشكل اختياري ملفات تعريف الارتباط هذه على مستوى عدة نطاقات استنادًا إلى خيارات الضبط التالية:

• يحفظ "g_state" حالة تسجيل خروج المستخدم ويتم ضبطه عند استخدام النافذة المنبثقة "نقرة واحدة" أو "تسجيل الدخول تلقائيًا".

• g_csrf_token هو ملف تعريف ارتباط مزدوج الإرسال يُستخدم لمنع هجمات CSRF، ويتم ضبطه عند استدعاء نقطة نهاية تسجيل الدخول. يمكن ضبط قيمة عنوان URI لتسجيل الدخول بشكل صريح أو قد يتم ضبطه تلقائيًا على معرّف الموارد المنتظم (URI) للصفحة الحالية. قد يتم طلب نقطة نهاية تسجيل الدخول وفقًا لهذه الشروط عند استخدام:

  • واجهة برمجة تطبيقات HTML مع data-ux_mode=redirect أو عند ضبط data-login_uri، أو

  • واجهة برمجة تطبيقات JavaScript مع ux_mode=redirect والتي لا تُستخدم فيها google.accounts.id.prompt() لعرض ميزة "نقرة واحدة" أو "تسجيل الدخول تلقائيًا".

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

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

مرجع نقل بيانات العناصر لتسجيل دخول المستخدم