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

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

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

  • تجربة المستخدم المضمّنة بنقرة واحدة وخطوات تجربة المستخدم اللاحقة:

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

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

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

  • "الدمج مرة واحدة" و"العرض في كل مكان"

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

    تسمح هذه البنية بفصل المخاوف، وبالتالي تقلل من تكلفة الدمج والصيانة.

  • الحدّ من نطاق التعرض للرمز المميّز للمعرّف:

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

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

  • عرض النطاقات بنقرة واحدة

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

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

  • دعم AMP.

    وفقًا للإعدادات التلقائية، لا يمكن عرض "نقرة واحدة من Google" في صفحات AMP للأسباب المذكورة أدناه.

    1. لا يُسمح بمكتبة JavaScript المخصّصة أو رمزها.

    2. قد تعرض ذاكرة التخزين المؤقت لصفحات AMP الصفحة من خلال نطاق آخر (عارض AMP).

    ويمكن إصلاح هذه المشكلة عن طريق الاستفادة من بنية iframe المتوسطة. بعد دمج ميزة "نقرة واحدة" في إطار iframe وسيط، يمكن للمطوّرين تضمينها في صفحات AMP من خلال إضافة مكوّن <amp-onetap-google>.

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

  • مخاطر الخصوصية:

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

  • المخاطر الأمنية:

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

عرض نقرة واحدة في إطار 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" في وضع iframe المتوسط. يمكنك تعيين نطاق واحد أو قائمة نطاقات مفصولة بفواصل كقيمة السمة. يمكن أيضًا استخدام النطاقات الفرعية التي تستخدم أحرف البدل.

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

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

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

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

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

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

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

  2. تساوي قيمة السمة offsetHeight للعنصر 0 عندما يكون مخفيًا.

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

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

<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:

<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 المتوسط.