आपकी स्क्रिप्ट को सुनना चाहिए, पोल नहीं करना चाहिए

सहमति पर निर्भर कोई भी स्क्रिप्ट — विज्ञापन टैग, एनालिटिक्स लोडर, हेडर बिडिंग रैपर — को दो बातें जाननी होती हैं: क्या CMP के पास अभी कोई निर्णय है, और वह निर्णय क्या है। एक आम गलती है पेज लोड पर कुकी पढ़ना, या कुछ दिखने तक टाइमर से CMP को पोल करते रहना। दोनों तरीके अनुमानित ढंग से विफल होते हैं: कुकी का फ़ॉर्मैट CMP का आंतरिक मामला है और बदल सकता है, और पोलिंग या तो बहुत जल्दी चल जाती है या इंतज़ार में समय बर्बाद करती है।

IAB TCF ठीक इसी काम के लिए एक मानक JavaScript इंटरफ़ेस परिभाषित करता है: __tcfapi फ़ंक्शन। यह ट्यूटोरियल उन कमांड, उन इवेंट और उन बग को क्रम से समझाता है जिनकी आपको वास्तव में ज़रूरत पड़ती है और जो प्रोडक्शन में सबसे ज़्यादा दिखते हैं।

स्टब और कतार

TCF CMP से अपेक्षा की जाती है कि वह पूरी CMP स्क्रिप्ट लोड होने से पहले, जितनी जल्दी संभव हो, पेज पर एक छोटा स्टब रखे। स्टब window.__tcfapi को परिभाषित करता है और CMP के तैयार होने से पहले किए गए किसी भी कॉल को कतार में रखता है। CMP के लोड हो जाने पर वह कतार को प्रोसेस करता है और हर कॉल का उत्तर देता है।

इसी कारण अन्य स्क्रिप्ट के लिए __tcfapi को तुरंत कॉल करना सुरक्षित है: जब तक स्टब उनसे पहले पेज में है, उनके कॉल खोते नहीं। यदि कोई स्क्रिप्ट इसलिए त्रुटि देती है कि __tcfapi परिभाषित नहीं है, तो स्टब या तो गायब है या बहुत देर से लोड हो रहा है — रीट्राई जोड़ने के बजाय लोड क्रम ठीक करें।

वे कमांड जो मायने रखते हैं

ping

__tcfapi('ping', 2, callback) उपयोगकर्ता के निर्णय की प्रतीक्षा किए बिना बुनियादी स्थिति लौटाता है। प्रतिक्रिया में cmpLoaded, stub, loading, loaded या error जैसा कोई cmpStatus, और visible, hidden या disabled में से कोई displayStatus शामिल होता है। यह ज्ञात होने पर 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 — एन्कोड की गई string, जिसे आप उन पार्टनर को आगे भेजते हैं जो इसकी अपेक्षा करते हैं।

उद्देश्य और विक्रेता दोनों जाँचें। विक्रेता की सहमति के बिना उद्देश्य की सहमति, या इसका उलटा, अधिकांश विक्रेताओं के लिए डेटा प्रोसेस करने हेतु पर्याप्त नहीं है।

iframe और क्रॉस-फ़्रेम कॉल

विज्ञापन और विजेट अक्सर ऐसे iframe के अंदर चलते हैं जो पैरेंट पेज के __tcfapi को नहीं देख सकते। TCF इसे postMessage प्रोटोकॉल से हल करता है: CMP शीर्ष पेज में __tcfapiLocator नाम का एक फ़्रेम जोड़ता है, और iframe के अंदर का कोड उसे ढूँढ सकता है, __tcfapiCall संदेश भेज सकता है और __tcfapiReturn प्रतिक्रिया पा सकता है। अधिकांश विज्ञापन SDK पहले से यही करते हैं। यदि आप अपना iframe कोड लिखते हैं, तो फ़्रेम के पार कुकी पढ़ने के बजाय यही पैटर्न लागू करें।

आम बग और उन्हें कैसे पहचानें

1. cmpuishown पर कार्रवाई करना। जो स्क्रिप्ट किसी भी कॉलबैक के चलते ही लोड हो जाती हैं, वे उपयोगकर्ता के निर्णय से पहले चल पड़ेंगी। eventStatus पर फ़िल्टर लगाएँ।
2. लिसनर को बहुत जल्दी हटाना। यदि आप उसे पहले कॉलबैक के बाद हटा देते हैं, तो आप बाद का useractioncomplete चूक जाएँगे और स्क्रिप्ट कभी लोड नहीं होगी।
3. वापसी को अनदेखा करना। स्थायी स्क्रिप्ट को सुनते रहना चाहिए और सहमति वापस लिए जाने पर खुद को रोकना या पुनः कॉन्फ़िगर करना चाहिए।
4. gdprApplies को अनदेखा करना। TCF क्षेत्रों के बाहर उद्देश्य ऑब्जेक्ट खाली हो सकते हैं; इसे “कोई सहमति नहीं” मान लेने से वह राजस्व बंद हो सकता है जिसे कमाने की आपको अनुमति है।
5. सफलता फ़्लैग न जाँचना। जब success false हो, तो उसे लॉग करें; यह आमतौर पर टूटे हुए CMP सेटअप का संकेत है।

अपने इंटीग्रेशन का परीक्षण

ब्राउज़र कंसोल में CMP की उपस्थिति की पुष्टि के लिए __tcfapi('ping', 2, console.log) कॉल करें, फिर कॉलबैक के रूप में console.log के साथ एक लिसनर पंजीकृत करें और बैनर पर क्लिक करके देखें। पहली विज़िट पर आपको cmpuishown के बाद useractioncomplete दिखना चाहिए, और रीलोड पर tcloaded। सभी स्वीकार करें, सभी अस्वीकार करें और कस्टम चयन के साथ दोहराएँ, और पुष्टि करें कि आपकी स्क्रिप्ट हर स्थिति में सही व्यवहार करती है।

मुख्य बातें

• CMP कुकी पढ़ने या पोलिंग के बजाय __tcfapi का उपयोग करें।
• सुनिश्चित करें कि API को कॉल करने वाली किसी भी स्क्रिप्ट से पहले CMP स्टब लोड हो।
• addEventListener का उपयोग करें और केवल tcloaded या useractioncomplete पर कार्रवाई करें।
• उद्देश्य और विक्रेता दोनों की स्थिति जाँचें, और gdprApplies का सम्मान करें।
• iframe के अंदर __tcfapiLocator postMessage पैटर्न का उपयोग करें।