Miksi skriptiesi pitäisi kuunnella eikä pollata

Jokaisen suostumuksesta riippuvan skriptin — mainostagin, analytiikkalataajan, header bidding -kääreen — on tiedettävä kaksi asiaa: onko CMP:llä jo päätös ja mikä se päätös on. Yleinen virhe on lukea eväste sivun latautuessa tai pollata CMP:tä ajastimella, kunnes jotain ilmestyy. Molemmat lähestymistavat hajoavat ennustettavasti: evästeen muoto on CMP:n sisäinen asia ja voi muuttua, ja pollaus joko laukeaa liian aikaisin tai tuhlaa aikaa odotteluun.

IAB TCF määrittelee tähän tehtävään standardin JavaScript-rajapinnan: funktion __tcfapi. Tämä opas käy läpi komennot, joita todella tarvitset, tapahtumat, joita saat, ja virheet, joita tuotannossa esiintyy useimmin.

Stub ja jono

TCF-CMP:n odotetaan sijoittavan sivulle mahdollisimman aikaisin, ennen täyden CMP-skriptin latautumista, pienen stubin. Stub määrittelee window.__tcfapi:n ja asettaa jonoon kaikki kutsut, jotka tehdään ennen kuin CMP on valmis. Kun CMP on latautunut, se käsittelee jonon ja vastaa jokaiseen kutsuun.

Tämä tekee muiden skriptien turvalliseksi kutsua __tcfapi:a heti: kunhan stub on sivulla ennen niitä, niiden kutsut eivät katoa. Jos skripti heittää virheen, koska __tcfapi on määrittelemätön, stub joko puuttuu tai latautuu liian myöhään — korjaa latausjärjestys sen sijaan, että lisäisit uudelleenyrityksiä.

Komennot, joilla on merkitystä

ping

__tcfapi('ping', 2, callback) palauttaa perustilan odottamatta käyttäjän päätöstä. Vastaus sisältää kentän cmpLoaded, arvon cmpStatus kuten stub, loading, loaded tai error, sekä kentän displayStatus arvolla visible, hidden tai disabled. Se ilmoittaa myös gdprApplies-arvon, kun se on tiedossa. Käytä sitä diagnostiikkaan ja päättämään, onko TCF ylipäätään merkityksellinen tälle kävijälle.

addEventListener

__tcfapi('addEventListener', 2, callback) on komento, jota useimpien integraatioiden tulisi käyttää. Callback saa tcData-objektin ja onnistumislipun, ja sitä kutsutaan uudelleen aina, kun suostumustila muuttuu. TCF v2.2:sta lähtien tämä on suositeltu tapa saada suostumustiedot; vanhempi getTCData-komento on poistettu käytöstä.

removeEventListener

Jokainen tcData-objekti sisältää listenerId:n. Välitä se funktiolle __tcfapi('removeEventListener', 2, callback, listenerId), kun skriptisi ei enää tarvitse päivityksiä — esimerkiksi kertakäyttöinen lataaja, joka on jo tehnyt päätöksensä.

eventStatusin lukeminen

Keskeinen kenttä tcData:ssa on eventStatus. Sillä on kolme arvoa:

• tcloaded — CMP löysi voimassa olevan tallennetun päätöksen, eikä banneria näytetä. Voit toimia tietojen perusteella heti.
• cmpuishown — banneri on näkyvissä. Tiedot kuvaavat aiempaa tilaa, mutta käyttäjä saattaa olla muuttamassa sitä.
• useractioncomplete — käyttäjä on juuri tehnyt tai vahvistanut valinnan. Toimi uusien tietojen perusteella.

Tyypillinen lataaja odottaa joko tcloaded- tai useractioncomplete-tapahtumaa ja tarkistaa sitten tarvitsemansa tarkoitukset ja toimittajat. Se ohittaa cmpuishown:n, paitsi ehkä kirjatakseen, että banneri ilmestyi.

Tarkoitusten ja toimittajien tarkistaminen

tcData:n sisällä suostumus ja oikeutettu etu esitetään ID:llä avainnettuina objekteina:

• tcData.purpose.consents[1] — suostumus tarkoitukseen 1 (laitteelle tallennus).
• tcData.purpose.legitimateInterests[7] — oikeutetun edun tila tarkoitukselle 7.
• tcData.vendor.consents[ID] ja tcData.vendor.legitimateInterests[ID] — toimittajakohtainen tila toimittajan Global Vendor List -tunnuksella.
• tcData.gdprApplies — onko CMP todennut GDPR:n soveltuvan tähän kävijään. Jos arvo on false, skriptisi tulisi noudattaa ei-TCF-logiikkaansa.
• tcData.tcString — koodattu merkkijono, jonka välität eteenpäin kumppaneille, jotka sitä odottavat.

Tarkista sekä tarkoitus että toimittaja. Tarkoituksen suostumus ilman toimittajan suostumusta tai päinvastoin ei riitä useimmille toimittajille tietojen käsittelyyn.

Iframet ja kehysten väliset kutsut

Mainokset ja widgetit toimivat usein iframeissa, jotka eivät näe pääsivun __tcfapi:a. TCF ratkaisee tämän postMessage-protokollalla: CMP lisää ylimmälle sivulle kehyksen nimeltä __tcfapiLocator, ja iframen sisällä oleva koodi voi löytää sen, lähettää __tcfapiCall-viestin ja vastaanottaa __tcfapiReturn-vastauksen. Useimmat mainos-SDK:t tekevät tämän jo. Jos kirjoitat oman iframe-koodin, toteuta sama malli sen sijaan, että lukisit evästeitä kehysten yli.

Yleiset virheet ja miten ne tunnistetaan

1. Toimiminen cmpuishown:n perusteella. Skriptit, jotka latautuvat heti kun mikä tahansa callback laukeaa, ajetaan ennen kuin käyttäjä on päättänyt. Suodata eventStatus:n mukaan.
2. Kuuntelijan poistaminen liian aikaisin. Jos poistat sen ensimmäisen callbackin jälkeen, myöhempi useractioncomplete jää huomaamatta eikä skripti koskaan lataudu.
3. Peruutusten sivuuttaminen. Pysyvien skriptien tulisi jatkaa kuuntelua ja pysähtyä tai määrittää itsensä uudelleen, kun suostumus peruutetaan.
4. gdprApplies:n sivuuttaminen. TCF-alueiden ulkopuolella tarkoitusobjektit voivat olla tyhjiä; sen tulkitseminen “ei suostumusta” voi sammuttaa tuloja, joita sinun on lupa ansaita.
5. Onnistumislipun tarkistamatta jättäminen. Kun success on false, kirjaa se; se viittaa yleensä rikkinäiseen CMP-määritykseen.

Integraation testaaminen

Kutsu selaimen konsolissa __tcfapi('ping', 2, console.log) varmistaaksesi, että CMP on paikalla, rekisteröi sitten kuuntelija, jonka callbackina on console.log, ja klikkaa banneri läpi. Ensimmäisellä käynnillä pitäisi näkyä cmpuishown ja sen jälkeen useractioncomplete, ja uudelleenlatauksessa tcloaded. Toista hyväksy kaikki -, hylkää kaikki - ja mukautetulla valinnalla ja varmista, että skriptisi toimii oikein jokaisessa tapauksessa.

Keskeiset opit

• Käytä __tcfapi:a sen sijaan, että lukisit CMP:n evästeitä tai pollaisit.
• Varmista, että CMP-stub latautuu ennen kaikkia skriptejä, jotka kutsuvat rajapintaa.
• Käytä addEventListener:ia ja toimi vain tcloaded- tai useractioncomplete-tapahtuman perusteella.
• Tarkista sekä tarkoituksen että toimittajan tila ja huomioi gdprApplies.
• Käytä iframeissa __tcfapiLocator-postMessage-mallia.