لماذا ينبغي لسكربتاتك أن تستمع لا أن تستطلع

أي سكربت يعتمد على الموافقة — وسم إعلاني، أو محمّل تحليلات، أو غلاف header bidding — يحتاج إلى معرفة أمرين: هل اتخذ CMP قرارًا بعد، وما هذا القرار. من الأخطاء الشائعة قراءة ملف تعريف ارتباط عند تحميل الصفحة، أو استطلاع CMP بمؤقّت حتى يظهر شيء ما. كلا النهجين يفشل بطرق متوقعة: فصيغة ملف تعريف الارتباط داخلية في CMP ويمكن أن تتغير، والاستطلاع إما ينطلق مبكرًا جدًا وإما يهدر الوقت في الانتظار.

تحدد IAB TCF واجهة JavaScript قياسية لهذه المهمة بالذات: الدالة __tcfapi. يستعرض هذا الدليل الأوامر التي تحتاجها فعلًا، والأحداث التي ستتلقاها، والأخطاء الأكثر ظهورًا في بيئة الإنتاج.

الـ Stub والطابور

يُتوقع من CMP الخاص بـ TCF أن يضع stub صغيرًا في الصفحة في أبكر وقت ممكن، قبل تحميل سكربت CMP الكامل. يعرّف الـ stub الدالة window.__tcfapi ويضع في طابور أي استدعاءات تتم قبل أن يصبح CMP جاهزًا. وعندما ينتهي CMP من التحميل يعالج الطابور ويجيب عن كل استدعاء.

وهذا ما يجعل من الآمن للسكربتات الأخرى استدعاء __tcfapi فورًا: ما دام الـ stub في الصفحة قبلها فلن تضيع استدعاءاتها. وإذا ألقى سكربت خطأً لأن __tcfapi غير معرّفة، فإما أن الـ stub مفقود أو أنه يُحمَّل متأخرًا — أصلح ترتيب التحميل بدلًا من إضافة محاولات إعادة.

الأوامر المهمة

ping

يعيد __tcfapi('ping', 2, callback) حالة أساسية دون انتظار قرار المستخدم. تتضمن الاستجابة cmpLoaded وcmpStatus مثل stub أو loading أو loaded أو error، وdisplayStatus بقيمة visible أو hidden أو disabled. كما تُبلغ عن gdprApplies متى عُرفت. استخدمه للتشخيص ولتقرر هل TCF ذو صلة بهذا الزائر أصلًا.

addEventListener

الأمر __tcfapi('addEventListener', 2, callback) هو الأمر الذي ينبغي لمعظم عمليات التكامل استخدامه. يتلقى الـ callback كائن tcData ومؤشر نجاح، ويُستدعى مجددًا في كل مرة تتغير فيها حالة الموافقة. منذ TCF v2.2 هذه هي الطريقة الموصى بها للحصول على بيانات الموافقة؛ أما الأمر الأقدم getTCData فقد أصبح مهجورًا.

removeEventListener

يحمل كل كائن tcData قيمة listenerId. مرّرها إلى __tcfapi('removeEventListener', 2, callback, listenerId) حين لا يحتاج سكربتك إلى مزيد من التحديثات — كمحمّل يعمل مرة واحدة وقد اتخذ قراره بالفعل.

قراءة eventStatus

الحقل الأساسي في tcData هو eventStatus. له ثلاث قيم:

• tcloaded — وجد CMP قرارًا مخزّنًا صالحًا ولن يُعرض أي بانر. يمكنك التصرف بناءً على البيانات فورًا.
• cmpuishown — البانر قيد العرض. تعكس البيانات أي حالة سابقة، لكن قد يكون المستخدم على وشك تغييرها.
• useractioncomplete — اتخذ المستخدم للتو اختيارًا أو أكّده. تصرّف بناءً على البيانات الجديدة.

ينتظر المحمّل النموذجي إما tcloaded أو useractioncomplete، ثم يفحص الأغراض والمزوّدين الذين يحتاجهم. ويتجاهل cmpuishown إلا ربما لتسجيل أن بانرًا ظهر.

فحص الأغراض والمزوّدين

داخل tcData تُعرض الموافقة والمصلحة المشروعة ككائنات مفهرسة بالمعرّف:

• tcData.purpose.consents[1] — الموافقة على الغرض 1 (التخزين على الجهاز).
• tcData.purpose.legitimateInterests[7] — حالة المصلحة المشروعة للغرض 7.
• tcData.vendor.consents[ID] وtcData.vendor.legitimateInterests[ID] — الحالة لكل مزوّد، باستخدام معرّف المزوّد في Global Vendor List.
• tcData.gdprApplies — هل حدّد CMP أن GDPR ينطبق على هذا الزائر. إذا كانت false فينبغي لسكربتك اتباع منطقه غير المرتبط بـ TCF.
• tcData.tcString — السلسلة المرمّزة، التي تمررها إلى الشركاء الذين يتوقعونها.

افحص الغرض والمزوّد معًا. موافقة على الغرض دون موافقة المزوّد، أو العكس، لا تكفي لمعظم المزوّدين لمعالجة البيانات.

الإطارات المضمّنة والاستدعاءات عبر الإطارات

غالبًا ما تعمل الإعلانات والأدوات داخل iframes لا ترى __tcfapi الخاصة بالصفحة الأم. يحل TCF ذلك ببروتوكول postMessage: يضيف CMP إطارًا باسم __tcfapiLocator إلى الصفحة العليا، ويمكن للشيفرة داخل iframe تحديد موقعه وإرسال رسالة __tcfapiCall واستلام استجابة __tcfapiReturn. تفعل معظم حزم SDK الإعلانية ذلك أصلًا. وإذا كتبت شيفرة iframe خاصة بك فطبّق النمط نفسه بدلًا من قراءة ملفات تعريف الارتباط عبر الإطارات.

الأخطاء الشائعة وكيف تكتشفها

1. التصرف بناءً على cmpuishown. السكربتات التي تُحمَّل بمجرد انطلاق أي callback ستعمل قبل أن يقرر المستخدم. صفِّ حسب eventStatus.
2. إزالة المستمع مبكرًا جدًا. إذا أزلته بعد أول callback فستفوتك useractioncomplete لاحقة ولن يتم التحميل أبدًا.
3. تجاهل حالات السحب. ينبغي للسكربتات الدائمة أن تواصل الاستماع وأن تتوقف أو تعيد ضبط نفسها عند سحب الموافقة.
4. تجاهل gdprApplies. خارج مناطق TCF قد تكون كائنات الأغراض فارغة؛ واعتبار ذلك «لا موافقة» قد يوقف إيرادات يحق لك كسبها.
5. عدم فحص مؤشر النجاح. عندما تكون قيمة success هي false فسجّل ذلك؛ فهو يشير عادةً إلى إعداد CMP معطوب.

اختبار التكامل لديك

في وحدة تحكم المتصفح، استدعِ __tcfapi('ping', 2, console.log) للتأكد من وجود CMP، ثم سجّل مستمعًا باستخدام console.log كـ callback وانقر عبر البانر. ينبغي أن ترى cmpuishown يليها useractioncomplete في الزيارة الأولى، وtcloaded عند إعادة التحميل. كرر ذلك مع قبول الكل ورفض الكل وتحديد مخصص، وتأكد من أن سكربتك يتصرف بشكل صحيح في كل حالة.

أهم النقاط

• استخدم __tcfapi بدلًا من قراءة ملفات تعريف ارتباط CMP أو الاستطلاع.
• تأكد من أن stub الخاص بـ CMP يُحمَّل قبل أي سكربت يستدعي الواجهة.
• استخدم addEventListener ولا تتصرف إلا عند tcloaded أو useractioncomplete.
• افحص حالة الغرض والمزوّد معًا، واحترم gdprApplies.
• استخدم نمط __tcfapiLocator مع postMessage داخل iframes.