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

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

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

المصادقة والتفويض

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

على غرار مكتبة منصة "تسجيل الدخول باستخدام حساب Google" السابقة، تم إنشاء مكتبة Google Identity Services الجديدة لتتوافق مع عمليات المصادقة والتفويض.

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

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

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

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

بالنسبة إلى المستخدمين، تقدّم مكتبة Google Identity Services الجديدة العديد من التحسينات على مستوى سهولة الاستخدام. تشمل الميزات ما يلي:

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

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

• الخيار الذي يتيح إضافة ميزة تسجيل الدخول إلى المحتوى الثابت في موقعك الإلكتروني باستخدام HTML فقط
• فلم يعُد من الضروري استخدام بروتوكول OAuth 2.0 المعقّد لتسجيل دخول المستخدمين إلى موقعك الإلكتروني، وذلك بسبب الفصل بين مصادقة تسجيل الدخول والتفويض ومشاركة بيانات المستخدمين.
• سيظلّ كلا الوضعين متاحًا، ولكن ستتم إعادة التوجيه الآن إلى نقطة نهاية تسجيل الدخول في خادم الخلفية ضمن بنية OAuth 2.0 الأساسية من Google.
• دمج الإمكانات من كلتا مكتبتَي JavaScript السابقتَين من Google Identity وGoogle API في مكتبة جديدة واحدة
• بالنسبة إلى ردود تسجيل الدخول، يمكنك الآن تحديد ما إذا كنت تريد استخدام Promise أو لا، كما تمت إزالة التوجيه غير المباشر من خلال دوال نمط 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.

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

• تستخدم تطبيقات الاختبار والإنتاج مشاريع منفصلة ولها أرقام تعريف عملاء خاصة بها،
• أنّ نوع معرّف عميل 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 العنصر السابقَين.

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

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

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

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

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

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

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

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

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

ردّ الرمز المميز

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

يتم عرض بيانات اعتماد صالحة لرمز مميّز للمعرّف بتنسيق JWT وموقّع من Google في إحدى الحالتَين التاليتَين:

• إلى معالج دالة الاستدعاء المستند إلى JavaScript في المتصفّح لدى المستخدم في وضع النافذة المنبثقة، أو
• إلى خادم الخلفية من خلال عملية إعادة توجيه من Google إلى نقطة نهاية تسجيل الدخول عندما يكون زر ux_mode "تسجيل الدخول باستخدام حساب Google" مضبوطًا على 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 Sign-in Platform Library.

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

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

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

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

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

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

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

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