Скрипттеріңіз неге сұрамай, тыңдауы керек

Келісімге тәуелді кез келген скрипт — жарнама тегі, аналитика жүктеушісі, header bidding орауышы — екі нәрсені білуі керек: CMP-де шешім бар-жоғын және бұл шешім не екенін. Жиі кездесетін қате — бет жүктелгенде cookie файлын оқу немесе бірдеңе пайда болғанша CMP-ді таймермен сұрап тұру. Екі тәсіл де болжауға болатын жолмен бұзылады: cookie форматы CMP-дің ішкі ісі және өзгеруі мүмкін, ал сұрау не тым ерте іске қосылады, не күтуге уақыт жұмсайды.

IAB TCF дәл осы жұмыс үшін стандартты JavaScript интерфейсін анықтайды: __tcfapi функциясы. Бұл нұсқаулық сізге шынымен қажет болатын командаларды, алатын оқиғаларыңызды және өндірісте жиі кездесетін қателерді қадам-қадаммен көрсетеді.

Stub және кезек

TCF CMP-ден толық CMP скрипті жүктелмес бұрын бетке мүмкіндігінше ерте шағын stub орналастыруы күтіледі. Stub window.__tcfapi функциясын анықтайды және CMP дайын болғанға дейін жасалған шақыруларды кезекке қояды. CMP жүктеліп біткенде, кезекті өңдейді және әр шақыруға жауап береді.

Дәл осы басқа скрипттерге __tcfapi функциясын бірден шақыруды қауіпсіз етеді: stub олардан бұрын бетте болса, шақырулар жоғалмайды. Егер скрипт __tcfapi анықталмағандықтан қате берсе, stub не жоқ, не тым кеш жүктелуде — қайталап көру қосудың орнына жүктеу ретін түзетіңіз.

Маңызды командалар

ping

__tcfapi('ping', 2, callback) пайдаланушы шешімін күтпестен негізгі күйді қайтарады. Жауапта cmpLoaded, stub, loading, loaded немесе error сияқты cmpStatus және visible, hidden немесе disabled мәндерінің бірі болатын displayStatus бар. Ол сондай-ақ белгілі болғанда 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 ішінде келісім мен заңды мүдде 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 — кодталған жол; оны күтетін серіктестерге бересіз.

Мақсатты да, жеткізушіні де тексеріңіз. Жеткізуші келісімінсіз мақсат келісімі немесе керісінше, көптеген жеткізушілердің деректерді өңдеуі үшін жеткіліксіз.

Iframe-дер және фреймаралық шақырулар

Жарнама мен виджеттер жиі аталық беттің __tcfapi функциясын көре алмайтын iframe-дер ішінде жұмыс істейді. TCF мұны postMessage протоколымен шешеді: CMP жоғарғы бетке __tcfapiLocator атты фрейм қосады, ал iframe ішіндегі код оны тауып, __tcfapiCall хабарын жібере алады және __tcfapiReturn жауабын ала алады. Көптеген жарнама SDK-лары мұны бұрыннан жасайды. Егер өз iframe кодыңызды жазсаңыз, фреймдер арасында cookie файлдарын оқудың орнына осы үлгіні жүзеге асырыңыз.

Жиі кездесетін қателер және оларды қалай анықтау

1. cmpuishown негізінде әрекет ету. Кез келген callback іске қосылысымен жүктелетін скрипттер пайдаланушы шешім қабылдағанша жұмыс істейді. eventStatus бойынша сүзгілеңіз.
2. Тыңдаушыны тым ерте алып тастау. Егер оны бірінші callback-тен кейін алып тастасаңыз, кейінгі useractioncomplete оқиғасын жіберіп аласыз және ешқашан жүктелмейсіз.
3. Келісімді қайтарып алуды елемеу. Тұрақты скрипттер тыңдауды жалғастырып, келісім қайтарылғанда тоқтауы немесе өзін қайта конфигурациялауы тиіс.
4. gdprApplies мәнін елемеу. TCF өңірлерінен тыс жерде мақсат нысандары бос болуы мүмкін; мұны “келісім жоқ” деп санау табуға рұқсат етілген кірісті өшіріп тастауы мүмкін.
5. Сәттілік жалауын тексермеу. success false болғанда, оны журналға жазыңыз; бұл әдетте бұзылған CMP орнатуын көрсетеді.

Интеграцияңызды тестілеу

Браузер консолінде CMP бар екенін растау үшін __tcfapi('ping', 2, console.log) шақырыңыз, содан кейін callback ретінде console.log бар тыңдаушыны тіркеп, баннер арқылы өтіңіз. Бірінші келуде cmpuishown және одан кейін useractioncomplete, қайта жүктегенде tcloaded көруіңіз керек. Барлығын қабылдау, барлығын қабылдамау және арнайы таңдаумен қайталаңыз және скриптіңіздің әр жағдайда дұрыс жұмыс істейтінін растаңыз.

Негізгі қорытындылар

• CMP cookie файлдарын оқу немесе сұраудың орнына __tcfapi пайдаланыңыз.
• API-ді шақыратын кез келген скриптің алдында CMP stub-ы жүктелетініне көз жеткізіңіз.
• addEventListener пайдаланыңыз және тек tcloaded немесе useractioncomplete негізінде әрекет етіңіз.
• Мақсат пен жеткізуші күйін тексеріңіз және gdprApplies мәнін құрметтеңіз.
• Iframe-дер ішінде __tcfapiLocator postMessage үлгісін пайдаланыңыз.