Kodėl jūsų skriptai turėtų klausytis, o ne apklausinėti

Kiekvienas nuo sutikimo priklausantis skriptas — reklamos žymė, analitikos įkroviklis, header bidding apvalkalas — turi žinoti du dalykus: ar CMP jau turi sprendimą ir koks tas sprendimas. Dažna klaida yra skaityti slapuką įkeliant puslapį arba apklausinėti CMP laikmačiu, kol kažkas atsiranda. Abu būdai sugenda nuspėjamai: slapuko formatas yra vidinis CMP dalykas ir gali pasikeisti, o apklausinėjimas arba suveikia per anksti, arba veltui laukia.

IAB TCF būtent šiai užduočiai apibrėžia standartinę JavaScript sąsają: funkciją __tcfapi. Šiame vadove aptariamos komandos, kurių iš tiesų reikia, įvykiai, kuriuos gausite, ir klaidos, dažniausiai pasitaikančios produkcijoje.

Stubas ir eilė

Tikimasi, kad TCF CMP kuo anksčiau, dar prieš įkeliant visą CMP skriptą, puslapyje patalpins mažą stubą. Stubas apibrėžia window.__tcfapi ir eilėje laiko visus iškvietimus, atliktus prieš CMP tampant pasiruošusiu. Kai CMP baigia įsikelti, jis apdoroja eilę ir atsako į kiekvieną iškvietimą.

Dėl to kitiems skriptams saugu iškviesti __tcfapi nedelsiant: jei stubas puslapyje yra prieš juos, jų iškvietimai nepranyksta. Jei skriptas meta klaidą, nes __tcfapi neapibrėžtas, stubo arba nėra, arba jis įkeliamas per vėlai — ištaisykite įkėlimo tvarką, o ne pridėkite pakartojimų.

Svarbios komandos

ping

__tcfapi('ping', 2, callback) grąžina pagrindinę būseną nelaukdama vartotojo sprendimo. Atsakyme yra cmpLoaded, cmpStatus (pvz., stub, loading, loaded arba error) ir displayStatus reikšmė visible, hidden arba disabled. Kai žinoma, nurodomas ir gdprApplies. Naudokite diagnostikai ir tam, kad nuspręstumėte, ar TCF šiam lankytojui apskritai aktualus.

addEventListener

__tcfapi('addEventListener', 2, callback) yra komanda, kurią turėtų naudoti dauguma integracijų. Callback gauna tcData objektą ir sėkmės vėliavėlę ir iškviečiamas dar kartą kaskart, kai pasikeičia sutikimo būsena. Nuo TCF v2.2 tai rekomenduojamas būdas gauti sutikimo duomenis; senesnė komanda getTCData buvo pažymėta kaip pasenusi.

removeEventListener

Kiekvienas tcData objektas turi listenerId. Perduokite jį į __tcfapi('removeEventListener', 2, callback, listenerId), kai jūsų skriptui atnaujinimų nebereikia — pavyzdžiui, vienkartiniam įkrovikliui, kuris jau priėmė sprendimą.

eventStatus skaitymas

Pagrindinis tcData laukas yra eventStatus. Yra trys reikšmės:

• tcloaded — CMP rado galiojantį išsaugotą sprendimą ir reklamjuostė nebus rodoma. Pagal duomenis galite veikti nedelsdami.
• cmpuishown — reklamjuostė rodoma. Duomenys atspindi bet kokią ankstesnę būseną, tačiau vartotojas gali ją tuoj pakeisti.
• useractioncomplete — vartotojas ką tik pasirinko arba patvirtino pasirinkimą. Veikite pagal naujus duomenis.

Tipiškas įkroviklis laukia tcloaded arba useractioncomplete, tada patikrina jam reikalingus tikslus ir tiekėjus. cmpuishown jis ignoruoja, daugiausia užregistruoja, kad reklamjuostė pasirodė.

Tikslų ir tiekėjų tikrinimas

Viduje tcData sutikimas ir teisėtas interesas pateikiami kaip objektai, indeksuojami pagal ID:

• tcData.purpose.consents[1] — sutikimas 1 tikslui (saugojimas įrenginyje).
• tcData.purpose.legitimateInterests[7] — teisėto intereso būsena 7 tikslui.
• tcData.vendor.consents[ID] ir tcData.vendor.legitimateInterests[ID] — kiekvieno tiekėjo būsena pagal tiekėjo ID Global Vendor List.
• tcData.gdprApplies — ar CMP nustatė, kad šiam lankytojui taikomas BDAR. Jei tai false, jūsų skriptas turėtų vadovautis ne TCF logika.
• tcData.tcString — užkoduota eilutė, kurią perduodate jos tikintis partneriams.

Tikrinkite ir tikslą, ir tiekėją. Sutikimas dėl tikslo be tiekėjo sutikimo, ar atvirkščiai, daugumai tiekėjų duomenims tvarkyti nepakanka.

Iframe ir iškvietimai tarp rėmelių

Reklamos ir valdikliai dažnai veikia iframe, kurie nemato tėvinio puslapio __tcfapi. TCF tai sprendžia postMessage protokolu: CMP į viršutinį puslapį prideda rėmelį, pavadintą __tcfapiLocator, o iframe esantis kodas gali jį surasti, išsiųsti __tcfapiCall pranešimą ir gauti __tcfapiReturn atsakymą. Dauguma reklamos SDK tai jau daro. Jei rašote savo iframe kodą, įgyvendinkite tą patį šabloną, užuot skaitę slapukus tarp rėmelių.

Dažnos klaidos ir kaip jas pastebėti

1. Veikimas pagal cmpuishown. Skriptai, įsikeliantys vos suveikus bet kuriam callback, pasileis prieš vartotojui apsisprendžiant. Filtruokite pagal eventStatus.
2. Per ankstyvas klausytojo pašalinimas. Jei pašalinsite po pirmojo callback, praleisite vėlesnį useractioncomplete ir niekada neįsikelsite.
3. Atšaukimų ignoravimas. Nuolat veikiantys skriptai turėtų toliau klausytis ir sustoti ar persikonfigūruoti, kai sutikimas atšaukiamas.
4. gdprApplies ignoravimas. Už TCF regionų tikslų objektai gali būti tušti; laikant tai “nėra sutikimo” galima išjungti pajamas, kurias leidžiama uždirbti.
5. Sėkmės vėliavėlės netikrinimas. Kai success yra false, užregistruokite tai; paprastai tai rodo sugadintą CMP sąranką.

Integracijos testavimas

Naršyklės konsolėje iškvieskite __tcfapi('ping', 2, console.log), kad patvirtintumėte, jog CMP yra, tada užregistruokite klausytoją su console.log kaip callback ir perkliksėkite reklamjuostę. Per pirmąjį apsilankymą turėtumėte matyti cmpuishown, o paskui useractioncomplete, o perkrovus — tcloaded. Pakartokite pasirinkdami priimti viską, atmesti viską ir pasirinktinį variantą ir patikrinkite, ar skriptas kiekvienu atveju elgiasi teisingai.

Pagrindinės išvados

• Naudokite __tcfapi, o ne skaitykite CMP slapukus ar apklausinėkite.
• Įsitikinkite, kad CMP stubas įsikelia prieš bet kurį API kviečiantį skriptą.
• Naudokite addEventListener ir veikite tik esant tcloaded arba useractioncomplete.
• Tikrinkite ir tikslo, ir tiekėjo būseną bei gerbkite gdprApplies.
• Iframe naudokite __tcfapiLocator postMessage šabloną.