الموافقة داخل iframes عبر الأصول: نمط __tcfapiLocator و__gppLocator

المشكلة: الموافقة تعيش في النافذة العليا

يعمل CMP على صفحتك، في النافذة العليا. أما كثير من إعلاناتك فلا. فالمواد الإبداعية المعروضة والوسائط الغنية ومُصيِّرات header bidding وكثير من أدوات الأطراف الثالثة تعمل داخل iframes، وغالبًا على أصل مختلف. والشيفرة في iframe عبر الأصول لا تستطيع استدعاء دالة في الصفحة الأم مباشرة، فلا يمكنها ببساطة استدعاء __tcfapi أو __gpp وقراءة اختيار الزائر.

تحلّ أطر IAB هذه المشكلة باتفاقية مراسلة صغيرة محددة جيدًا. وإذا كنت تبني منتجات إعلانية أو عناصر مضمَّنة أو نصوص قياس تعمل في إطارات، أو تصحّح منظومات إعلانات تفعل ذلك، فمن المفيد أن تعرف بالضبط كيف تعمل.

إطار locator

إلى جانب واجهة JavaScript، يضيف CMP الخاص بـ TCF إلى الصفحة العليا iframe فارغًا غير مرئي باسم __tcfapiLocator. ويفعل CMP الخاص بـ GPP الشيء نفسه بإطار باسم __gppLocator. لا تحمل الإطارات أي محتوى. وظيفتها الوحيدة أن يمكن العثور عليها: يستطيع أي نص في أي إطار متداخل أن يصعد في تسلسل النوافذ ويتحقق مما إذا كان إطار بهذا الاسم موجودًا عند كل مستوى.

ولأن أسماء الإطارات مرئية عبر الأصول من خلال window.frames، يستطيع نص في iframe متداخل بعمق وعبر الأصول أن يحدد النافذة التي تستضيف CMP دون أن يملك وصولًا إلى أي شيء آخر في تلك الصفحة.

كيف يجد النص المؤطَّر CMP

  1. ابدأ بالنافذة الحالية. إذا كانت __tcfapi موجودة محليًا، فاستخدمها مباشرة — النص ليس في إطار، أو أن الإطار يشارك CMP.
  2. وإلا فاصعد في حلقة: تحقق مما إذا كانت النافذة الحالية تحتوي على إطار باسم __tcfapiLocator؛ فإن لم تجد، فانتقل إلى window.parent وتحقق مجددًا، وتوقف عند النافذة العليا.
  3. حين يُعثر على locator، تكون النافذة التي تحتويه هي نافذة CMP. ويجري التواصل الآن عبر postMessage.

غلّف كل وصول بـ try/catch، لأن بعض المتصفحات أو إعدادات العزل ترمي استثناءً عند الوصول إلى خاصية عبر الأصول، وأوقف الحلقة حين تساوي window.parent النافذة الحالية.

صيغة الرسالة

في TCF، يرسل النص المؤطَّر رسالة إلى نافذة CMP تحتوي كائنًا بخاصية __tcfapiCall. وبداخلها أربعة حقول:

يستمع CMP إلى هذه الرسائل، وينفّذ الأمر، ويرسل كائنًا بخاصية __tcfapiReturn يحتوي returnValue وsuccess وcallId نفسه. ويحتفظ المستدعي بخريطة من callbacks المعلّقة مفهرسة بـ callId، ويستمع إلى أحداث message، ويوجّه كل ردّ إلى callback الصحيح. ويتبع GPP النمط نفسه مع __gppCall و__gppReturn.

تكتب كثير من التكاملات وكيلًا صغيرًا: دالة محلية باسم __tcfapi داخل الإطار تحوّل الاستدعاءات إلى رسائل. فتعمل الشيفرة المكتوبة للنافذة العليا دون تغيير داخل الإطار.

مستمعو الأحداث عبر الإطارات

استدعاء addEventListener المرسَل عبر postMessage ليس طلبًا لمرة واحدة. سيرسل CMP رسالة ردّ في كل مرة تتغير فيها حالة الموافقة، وكلها بـ callId نفسه. لذا يجب أن يُبقي موزّعك ذلك callback مسجَّلًا بدلًا من حذفه بعد أول استجابة. ونسيان هذا خطأ كلاسيكي: يقرأ النص المؤطَّر الموافقة مرة واحدة ولا يلاحظ سحبًا لاحقًا.

اعتبارات الأمان

حيث لا يصل هذا النمط

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

قائمة التصحيح

أهم النقاط

← المدونة قراءة الكل →