آپ کے اسکرپٹس کو پولنگ نہیں، سننا چاہیے

کوئی بھی اسکرپٹ جو رضامندی پر منحصر ہو — اشتہاری ٹیگ، اینالیٹکس لوڈر، ہیڈر بڈنگ ریپر — کو دو باتیں جاننی ہوتی ہیں: کیا CMP نے ابھی تک کوئی فیصلہ کیا ہے، اور وہ فیصلہ کیا ہے۔ ایک عام غلطی یہ ہے کہ پیج لوڈ پر کوکی پڑھ لی جائے، یا ٹائمر کے ذریعے CMP کی پولنگ کی جائے جب تک کچھ ظاہر نہ ہو۔ دونوں طریقے متوقع انداز میں ناکام ہوتے ہیں: کوکی کا فارمیٹ CMP کا اندرونی معاملہ ہے اور بدل سکتا ہے، اور پولنگ یا تو بہت جلدی چل پڑتی ہے یا انتظار میں وقت ضائع کرتی ہے۔

IAB TCF اسی کام کے لیے ایک معیاری JavaScript انٹرفیس بیان کرتا ہے: __tcfapi فنکشن۔ یہ ٹیوٹوریل ان کمانڈز کا جائزہ لیتا ہے جن کی آپ کو واقعی ضرورت ہے، ان ایونٹس کا جو آپ کو ملیں گے، اور ان بگز کا جو پروڈکشن میں سب سے زیادہ سامنے آتے ہیں۔

اسٹب اور قطار

TCF CMP سے توقع کی جاتی ہے کہ وہ مکمل CMP اسکرپٹ لوڈ ہونے سے پہلے، جتنی جلدی ممکن ہو، پیج پر ایک چھوٹا stub رکھے۔ اسٹب window.__tcfapi کو متعین کرتا ہے اور CMP کے تیار ہونے سے پہلے کی جانے والی کسی بھی کال کو قطار میں رکھ لیتا ہے۔ جب CMP لوڈ مکمل کر لیتا ہے تو قطار پراسیس کرتا ہے اور ہر کال کا جواب دیتا ہے۔

یہی چیز دوسرے اسکرپٹس کے لیے __tcfapi کو فوراً کال کرنا محفوظ بناتی ہے: جب تک اسٹب ان سے پہلے پیج میں موجود ہے، ان کی کالز ضائع نہیں ہوتیں۔ اگر کوئی اسکرپٹ اس لیے ایرر دیتا ہے کہ __tcfapi غیر متعین ہے تو اسٹب یا تو موجود نہیں یا بہت دیر سے لوڈ ہو رہا ہے — دوبارہ کوششیں شامل کرنے کے بجائے لوڈ کی ترتیب درست کریں۔

اہم کمانڈز

ping

__tcfapi('ping', 2, callback) صارف کے فیصلے کا انتظار کیے بغیر بنیادی حالت لوٹاتی ہے۔ جواب میں cmpLoaded، ایک cmpStatus جیسے stub، loading، loaded یا error، اور displayStatus شامل ہوتا ہے جس کی قدر visible، hidden یا disabled ہو سکتی ہے۔ یہ معلوم ہونے پر gdprApplies بھی بتاتی ہے۔ اسے تشخیص کے لیے اور یہ طے کرنے کے لیے استعمال کریں کہ آیا TCF اس وزیٹر کے لیے متعلقہ ہے بھی یا نہیں۔

addEventListener

__tcfapi('addEventListener', 2, 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 کے اندر رضامندی اور جائز مفاد ID کی بنیاد پر آبجیکٹس کی شکل میں سامنے آتے ہیں:

• tcData.purpose.consents[1] — مقصد 1 (ڈیوائس اسٹوریج) کے لیے رضامندی۔
• tcData.purpose.legitimateInterests[7] — مقصد 7 کے لیے جائز مفاد کی حالت۔
• tcData.vendor.consents[ID] اور tcData.vendor.legitimateInterests[ID] — ہر وینڈر کی حالت، وینڈر کی Global Vendor List ID استعمال کرتے ہوئے۔
• tcData.gdprApplies — آیا CMP نے طے کیا کہ اس وزیٹر پر GDPR لاگو ہوتا ہے۔ اگر یہ false ہو تو آپ کے اسکرپٹ کو اپنی غیر-TCF منطق پر عمل کرنا چاہیے۔
• tcData.tcString — انکوڈ شدہ اسٹرنگ، جو آپ ان پارٹنرز کو دیتے ہیں جو اس کی توقع رکھتے ہیں۔

مقصد اور وینڈر دونوں کو چیک کریں۔ وینڈر کی رضامندی کے بغیر مقصد کی رضامندی، یا اس کے برعکس، زیادہ تر وینڈرز کے لیے ڈیٹا پراسیس کرنے کو کافی نہیں۔

آئی فریمز اور کراس فریم کالز

اشتہارات اور ویجٹس اکثر ایسے iframes کے اندر چلتے ہیں جو پیرنٹ پیج کا __tcfapi نہیں دیکھ سکتے۔ TCF اسے postMessage پروٹوکول سے حل کرتا ہے: CMP اوپری پیج میں __tcfapiLocator نام کا فریم شامل کرتا ہے، اور iframe کے اندر کا کوڈ اسے تلاش کر سکتا ہے، __tcfapiCall پیغام بھیج سکتا ہے اور __tcfapiReturn جواب وصول کر سکتا ہے۔ زیادہ تر اشتہاری SDKs پہلے ہی ایسا کرتے ہیں۔ اگر آپ اپنا iframe کوڈ لکھتے ہیں تو فریمز کے پار کوکیز پڑھنے کے بجائے یہی پیٹرن نافذ کریں۔

عام بگز اور انہیں پہچاننے کا طریقہ

1. cmpuishown پر عمل کرنا۔ جو اسکرپٹس کسی بھی کال بیک کے چلتے ہی لوڈ ہو جاتے ہیں وہ صارف کے فیصلے سے پہلے چل پڑیں گے۔ eventStatus پر فلٹر لگائیں۔
2. لسنر کو بہت جلد ہٹانا۔ اگر آپ اسے پہلی کال بیک کے بعد ہٹا دیں تو آپ بعد کی useractioncomplete سے محروم ہو جائیں گے اور کبھی لوڈ نہیں ہوگا۔
3. رضامندی واپس لینے کو نظر انداز کرنا۔ مستقل اسکرپٹس کو سنتے رہنا چاہیے اور رضامندی واپس لیے جانے پر رک جانا یا خود کو دوبارہ ترتیب دینا چاہیے۔
4. gdprApplies کو نظر انداز کرنا۔ TCF والے علاقوں کے باہر مقصد کے آبجیکٹس خالی ہو سکتے ہیں؛ اسے “رضامندی نہیں” سمجھنا وہ آمدنی بند کر سکتا ہے جو کمانے کی آپ کو اجازت ہے۔
5. کامیابی کا فلیگ چیک نہ کرنا۔ جب success false ہو تو اسے لاگ کریں؛ یہ عموماً CMP سیٹ اپ کے ٹوٹے ہونے کا اشارہ ہوتا ہے۔

اپنے انضمام کی جانچ

براؤزر کنسول میں __tcfapi('ping', 2, console.log) کال کر کے تصدیق کریں کہ CMP موجود ہے، پھر console.log کو کال بیک بنا کر لسنر رجسٹر کریں اور بینر پر کلک کرتے جائیں۔ پہلی وزٹ پر آپ کو cmpuishown کے بعد useractioncomplete نظر آنا چاہیے، اور ری لوڈ پر tcloaded۔ سب قبول کریں، سب مسترد کریں اور حسب ضرورت انتخاب کے ساتھ دہرائیں، اور تصدیق کریں کہ آپ کا اسکرپٹ ہر صورت میں درست برتاؤ کرتا ہے۔

اہم نکات

• CMP کی کوکیز پڑھنے یا پولنگ کے بجائے __tcfapi استعمال کریں۔
• یقینی بنائیں کہ CMP اسٹب ہر اس اسکرپٹ سے پہلے لوڈ ہو جو API کو کال کرتا ہے۔
• addEventListener استعمال کریں اور صرف tcloaded یا useractioncomplete پر عمل کریں۔
• مقصد اور وینڈر دونوں کی حالت چیک کریں، اور gdprApplies کا احترام کریں۔
• iframes کے اندر __tcfapiLocator والا postMessage پیٹرن استعمال کریں۔