Miks sinu skriptid peaksid kuulama, mitte pollima

Iga nõusolekust sõltuv skript — reklaamimärgend, analüütika laadija, header bidding'u ümbris — peab teadma kahte asja: kas CMP-l on otsus juba olemas ja milline see otsus on. Levinud viga on lugeda küpsist lehe laadimisel või pollida CMP-d taimeriga, kuni midagi ilmub. Mõlemad lähenemised lähevad ennustataval viisil katki: küpsise vorming on CMP sisemine ja võib muutuda ning pollimine kas käivitub liiga vara või raiskab aega ootamisele.

IAB TCF defineerib just selleks otstarbeks standardse JavaScripti liidese: funktsiooni __tcfapi. See õpetus käib läbi käsud, mida sa tegelikult vajad, sündmused, mida saad, ja vead, mis tootmises kõige sagedamini ilmnevad.

Stub ja järjekord

TCF-i CMP-lt oodatakse, et ta paneb lehele võimalikult vara, enne täieliku CMP-skripti laadimist, väikese stubi. Stub defineerib window.__tcfapi ja paneb järjekorda kõik kutsed, mis tehakse enne CMP valmimist. Kui CMP on laadimise lõpetanud, töötleb ta järjekorra läbi ja vastab igale kutsele.

Just see teeb teistel skriptidel turvaliseks kutsuda __tcfapi kohe: kuni stub on lehel nende ees, ei lähe nende kutsed kaduma. Kui skript viskab vea, sest __tcfapi on defineerimata, siis stub kas puudub või laadib liiga hilja — paranda laadimisjärjekorda, mitte korduskatseid.

Käsud, mis loevad

ping

__tcfapi('ping', 2, callback) tagastab põhilise oleku, ootamata kasutaja otsust. Vastus sisaldab välja cmpLoaded, väärtust cmpStatus nagu stub, loading, loaded või error, ning välja displayStatus väärtusega visible, hidden või disabled. Samuti teatab see gdprApplies, kui see on teada. Kasuta seda diagnostikaks ja otsustamiseks, kas TCF on selle külastaja jaoks üldse asjakohane.

addEventListener

__tcfapi('addEventListener', 2, callback) on käsk, mida enamik integratsioone peaks kasutama. Tagasikutse saab tcData objekti ja edu lipu ning seda kutsutakse uuesti iga kord, kui nõusoleku olek muutub. Alates TCF v2.2-st on see soovitatud viis nõusolekuandmete saamiseks; vanem käsk getTCData on iganenud.

removeEventListener

Iga tcData objekt kannab listenerId-d. Anna see funktsioonile __tcfapi('removeEventListener', 2, callback, listenerId), kui sinu skript ei vaja enam uuendusi — näiteks ühekordne laadija, mis on oma otsuse juba teinud.

eventStatus'i lugemine

Võtmeväli objektis tcData on eventStatus. Sellel on kolm väärtust:

• tcloaded — CMP leidis kehtiva salvestatud otsuse ja bännerit ei kuvata. Andmete põhjal saad tegutseda kohe.
• cmpuishown — bännerit kuvatakse. Andmed kajastavad varasemat olekut, kuid kasutaja võib seda parasjagu muutmas olla.
• useractioncomplete — kasutaja tegi või kinnitas äsja valiku. Tegutse uute andmete põhjal.

Tüüpiline laadija ootab kas tcloaded või useractioncomplete, seejärel kontrollib vajalikke eesmärke ja pakkujaid. Ta ignoreerib cmpuishown-i, välja arvatud ehk logimaks, et bänner ilmus.

Eesmärkide ja pakkujate kontrollimine

Objektis tcData on nõusolek ja õigustatud huvi esitatud ID järgi võtmestatud objektidena:

• tcData.purpose.consents[1] — nõusolek eesmärgile 1 (seadmesse salvestamine).
• tcData.purpose.legitimateInterests[7] — õigustatud huvi olek eesmärgile 7.
• tcData.vendor.consents[ID] ja tcData.vendor.legitimateInterests[ID] — pakkujapõhine olek, kasutades pakkuja Global Vendor Listi ID-d.
• tcData.gdprApplies — kas CMP tuvastas, et sellele külastajale kohaldub GDPR. Kui see on false, peaks sinu skript järgima oma mitte-TCF loogikat.
• tcData.tcString — kodeeritud string, mille annad edasi partneritele, kes seda ootavad.

Kontrolli nii eesmärki kui ka pakkujat. Eesmärgi nõusolek ilma pakkuja nõusolekuta või vastupidi ei piisa enamikule pakkujatest andmete töötlemiseks.

Iframe'id ja kaadriülesed kutsed

Reklaamid ja vidinad töötavad sageli iframe'ides, mis ei näe vanemlehe __tcfapi-d. TCF lahendab selle postMessage protokolliga: CMP lisab ülemisele lehele kaadri nimega __tcfapiLocator ning iframe'i sees olev kood saab selle leida, saata sõnumi __tcfapiCall ja saada vastuse __tcfapiReturn. Enamik reklaami-SDK-sid teeb seda juba. Kui kirjutad oma iframe'i koodi, rakenda sama mustrit, mitte ära loe küpsiseid üle kaadrite.

Levinumad vead ja kuidas neid märgata

1. Tegutsemine cmpuishown põhjal. Skriptid, mis laadivad niipea, kui mõni tagasikutse käivitub, töötavad enne, kui kasutaja on otsustanud. Filtreeri eventStatus'i järgi.
2. Kuulaja eemaldamine liiga vara. Kui eemaldad selle pärast esimest tagasikutset, jääb sul hilisem useractioncomplete märkamata ja skript ei laadi kunagi.
3. Tagasivõtmiste ignoreerimine. Püsivad skriptid peaksid jätkama kuulamist ning peatuma või ümber seadistuma, kui nõusolek võetakse tagasi.
4. gdprApplies ignoreerimine. Väljaspool TCF-i piirkondi võivad eesmärgiobjektid olla tühjad; selle käsitlemine kui “nõusolek puudub” võib välja lülitada tulu, mida sul on lubatud teenida.
5. Edu lipu kontrollimata jätmine. Kui success on false, logi see; see viitab tavaliselt katkisele CMP seadistusele.

Integratsiooni testimine

Kutsu brauseri konsoolis __tcfapi('ping', 2, console.log), et veenduda CMP olemasolus, seejärel registreeri kuulaja, mille tagasikutseks on console.log, ja klõpsa bänner läbi. Esmakülastusel peaksid nägema cmpuishown-i, millele järgneb useractioncomplete, ja uuesti laadimisel tcloaded-i. Korda nõustu-kõigega, keeldu-kõigest ja kohandatud valikuga ning veendu, et sinu skript käitub igal juhul õigesti.

Peamised järeldused

• Kasuta __tcfapi-d CMP küpsiste lugemise ja pollimise asemel.
• Veendu, et CMP stub laadib enne mis tahes skripti, mis API-t kutsub.
• Kasuta addEventListener-it ja tegutse ainult tcloaded või useractioncomplete korral.
• Kontrolli nii eesmärgi kui ka pakkuja olekut ning austa gdprApplies-i.
• Kasuta iframe'ides __tcfapiLocator postMessage mustrit.