دمج ميزة "نقرة واحدة" باستخدام إطار iframe

يمكن عرض ميزة "نقرة Google One" داخل إطار iframe (ويُشار إليه في ما يلي باسم "إطار iframe المتوسط") الذي يستضيفه موقعك الإلكتروني. ليس هناك أي تغيير ملموس في تجربة المستخدم بنقرة واحدة عند استخدام إطار iframe وسيط.

يوفّر الدمج المستند إلى إطار iframe المتوسط بعض المرونة والمخاطر:

تجربة المستخدم المُضمَّنة لميزة "نقرة واحدة" وخطوات لاحقة لتجربة المستخدم:

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

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

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

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

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

وتعمل طريقة iframe المتوسطة أيضًا بشكل جيد مع مواقع الويب التي تحتوي من قبل على نطاق فرعي مخصص مرتبط بتسجيل الدخول (على سبيل المثال،login.example.com) ونطاقات فرعية متعددة مرتبطة بالمحتوى (على سبيل المثال، Sports.example.com وgames.example.com).
عرض النطاقات بنقرة واحدة

وفقًا لما تقتضيه سياسات OAuth في Google، يجب أن تكون جميع النطاقات التي تتلقّى ردودًا عبر بروتوكول OAuth مسجَّلة مسبقًا في وحدة تحكُّم واجهة برمجة تطبيقات Google. من خلال عملية دمج One Tap العادية، يحتاج المطوّرون إلى التسجيل المُسبَق في جميع النطاقات التي قد تعرضها ميزة One Tap، وذلك لأنّه ستتم إعادة الرموز المميّزة للمعرّفات إلى هذه النطاقات. تتيح بعض المواقع الإلكترونية لمستخدميها إنشاء نطاقات فرعية ديناميكيًا، والتي يستحيل تسجيلها مسبقًا. ونتيجةً لذلك، لا يمكن عرض "نقرة واحدة" في هذه النطاقات الفرعية التي تم إنشاؤها ديناميكيًا.

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

تحذير: لن يكون مكوّن AMP One Tap متاحًا بعد الإيقاف النهائي لملفات تعريف الارتباط التابعة لجهات خارجية في Chrome بدءًا من 1 في المئة من ملفات تعريف الارتباط التابعة لجهات خارجية في الربع الأول من عام 2024، والوصول إلى 100 بالمئة من مستخدمي Chrome في النصف الثاني من عام 2024. ويعني هذا أنّه يجب ألّا تستخدم تطبيقات الويب الجديدة هذا المكوِّن، وعلى مطوّري التطبيقات الحالية اتّباع دليل نقل البيانات لإجراء التغييرات الضرورية من أجل تجنُّب التأثيرات السلبية على تسجيل دخول المستخدم إلى مواقعهم الإلكترونية.

وفقًا للإعدادات التلقائية، لا يمكن عرض "نقرة Google One" في صفحات AMP لبعض الأسباب التالية:
1. غير مسموح بمكتبة JavaScript المخصّصة أو رمزها.
2. قد تعرض ذاكرة التخزين المؤقت لصفحات AMP الصفحة على شكل نطاق آخر (عارض AMP).
ويمكن إصلاح هذه المشكلة من خلال الاستفادة من بنية iframe الوسيطة. بعد دمج ميزة "نقرة واحدة" في إطار iframe متوسط، يمكن لمطوّري البرامج تضمينها في صفحات AMP من خلال إضافة مكوِّن <amp-onetap-google>.

يمكن إعادة استخدام إطار iframe المتوسط نفسه بواسطة صفحات AMP وصفحات HTML التي ليست بتنسيق AMP.
مخاطر الخصوصية:

على المطوّرين اتّخاذ تدابير لمنع تضمين إطارات iframe الوسيطة في نطاقات غير متوقعة. على سبيل المثال، قد يضمِّن Spam.com إطار iframe المتوسط، وبالتالي يعرض تجربة المستخدم بنقرة واحدة على موقعه الإلكتروني. سيؤدي هذا بالتأكيد إلى الكثير من المخاوف المتعلقة بالخصوصية من المستخدمين النهائيين.

تحذير: إنّ تجربة المستخدم اللاحقة عرضة أيضًا لإطارات غير متوقّعة. قد يزيّف المهاجمون عنوان URL لتضمين واجهة مستخدم واحدة لتجربة المستخدم التالية مباشرةً. احرص على إثبات صحة مصدر إطار iframe الرئيسي في كل خطوة من خطوات تجربة المستخدم اللاحقة.
نقطة رئيسية: يمكنك إثبات صحة المصدر الرئيسي من خلال طلب واجهة برمجة التطبيقات verifyParentOrigin من مكتبة الدعم المتوسط لإطار iframe في كل خطوة من خطوات تجربة المستخدم اللاحقة.
ملاحظة: لا حاجة إلى استدعاء واجهة برمجة التطبيقات verifyParentOrigin عند عرض ميزة "نقرة واحدة". سبق أن تم إثبات الهوية من خلال ميزة "نقرة واحدة". يجب طلب البيانات من واجهة برمجة التطبيقات verifyParentOrigin فقط عند تنفيذ تجربة المستخدم اللاحقة.
المخاطر الأمنية:

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

تحذير: يجب ألا يرسل إطار iframe المتوسط رموز OAuth المميزة أو قيم ملفات تعريف ارتباط الجلسات أو بيانات المستخدمين إلى الإطار الرئيسي.

عرض "نقرة واحدة" في إطار iframe المتوسط

لعرض "نقرة واحدة" داخل إطار iframe المتوسط، ضَع مقتطف الرمز التالي في رمز HTML لإطار iframe المتوسط:

<div id="g_id_onload"
     data-client_id="YOUR_GOOGLE_CLIENT_ID"
     data-login_uri="https://your.domain/your_login_endpoint"
     data-allowed_parent_origin="https://example.com">
</div>

إذا تم استخدام السمة data-allowed_parent_origin، يتم تشغيل ميزة "نقرة Google One" في وضع iframe المتوسط. يمكنك ضبط نطاق واحد أو قائمة نطاقات مفصولة بفواصل كقيمة السمة. يمكن أيضًا استخدام النطاقات الفرعية التي تتضمّن أحرف البدل.

(اختياري) عرض تجربة المستخدم اللاحقة في إطار Iframe المتوسط

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

يمكنك تغيير حجم إطار iframe المتوسط:

<script src="https://accounts.google.com/gsi/intermediatesupport"></script>
<script>
  google.accounts.id.intermediate.notifyParentResize(320);
</script>

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

بالنسبة إلى الصفحة الأولى بعد "تجربة المستخدم بنقرة واحدة"، عليك طلب طريقة notifyParentResize() مرتين للأسباب التالية.

ويتم ضبط إطار iframe المتوسط على "مخفي" عند انتهاء "تجربة المستخدم بنقرة واحدة".
وتكون قيمة السمة offsetHeight لعنصر ما هي 0 عندما يكون مخفيًا.

في الاستدعاء الأول، يمكنك تغيير حجم ارتفاع iframe إلى 1 بكسل فقط لجعله مرئيًا. وبعد ذلك، بعد توفّر قيمة السمة offsetHeight، يمكنك تغيير حجمها إلى ارتفاع مناسب.

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

<script>
window.onload = () => {
  google.accounts.id.intermediate.verifyParentOrigin(
    ["https://example.com","https://example-com.cdn.ampproject.org"],
    () => {
      google.accounts.id.intermediate.notifyParentResize(1);
      window.setTimeout(() => {
        let h = document.getElementById('container').offsetHeight;
        google.accounts.id.intermediate.notifyParentResize(h);
      }, 200);
    },
    () => {
      document.getElementById('container').style.display = 'none';
      document.getElementById('warning').innerText = 'Warning: the page is displayed in an unexpected domain!';
    }
  );
};
</script>

إزالة إطار Iframe متوسط على تجربة المستخدم

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

<script src="https://accounts.google.com/gsi/intermediatesupport"></script>
<script>
  google.accounts.id.intermediate.notifyParentDone();
</script>

وإذا تم تخطي مسار تجربة المستخدم، يجب استدعاء طريقة notifyParentClose بدلاً من ذلك.

تضمين إطار iframe المتوسط في صفحات HTML

ضَع مقتطف الرمز التالي في أي صفحة HTML تريد أن يعرضها Google One Tap:

<script src="https://accounts.google.com/gsi/intermediate"></script>
<div id="g_id_intermediate_iframe"
     data-src="https://example.com/onetap_iframe.html">
</div>

السمة data-src هي معرّف الموارد المنتظم (URI) لإطار iframe المتوسط.