Kāpēc skriptiem jāklausās, nevis jāaptauja

Jebkuram skriptam, kas ir atkarīgs no piekrišanas — reklāmas tagam, analītikas ielādētājam, header bidding apvalkam — jāzina divas lietas: vai CMP jau ir pieņēmis lēmumu un kāds šis lēmums ir. Bieži pieļauta kļūda ir nolasīt sīkdatni lapas ielādes brīdī vai aptaujāt CMP ar taimeri, līdz kaut kas parādās. Abas pieejas salūst paredzamā veidā: sīkdatnes formāts ir CMP iekšēja lieta un var mainīties, bet aptaujāšana vai nostrādā pārāk agri, vai velti gaida.

IAB TCF šim uzdevumam definē standarta JavaScript saskarni: funkciju __tcfapi. Šī pamācība izskaidro komandas, kas jums tiešām vajadzīgas, notikumus, ko saņemsiet, un kļūdas, kas ražošanā parādās visbiežāk.

Stub un rinda

No TCF CMP tiek sagaidīts, ka tas lapā pēc iespējas agrāk, pirms pilnā CMP skripta ielādes, ievieto nelielu stub. Stub definē window.__tcfapi un ievieto rindā visus izsaukumus, kas veikti, pirms CMP ir gatavs. Kad CMP ielāde ir pabeigta, tas apstrādā rindu un atbild uz katru izsaukumu.

Tieši tāpēc citi skripti var droši izsaukt __tcfapi uzreiz: ja stub lapā ir pirms tiem, to izsaukumi netiek zaudēti. Ja skripts met kļūdu, jo __tcfapi nav definēts, stub vai nu trūkst, vai tiek ielādēts par vēlu — labojiet ielādes secību, nevis pievienojiet atkārtotus mēģinājumus.

Komandas, kas ir svarīgas

ping

__tcfapi('ping', 2, callback) atgriež pamata statusu, negaidot lietotāja lēmumu. Atbildē ir iekļauts cmpLoaded, cmpStatus ar vērtību, piemēram, stub, loading, loaded vai error, un displayStatus ar vērtību visible, hidden vai disabled. Tā ziņo arī par gdprApplies, tiklīdz tas ir zināms. Izmantojiet to diagnostikai un lai izlemtu, vai TCF šim apmeklētājam vispār ir būtisks.

addEventListener

__tcfapi('addEventListener', 2, callback) ir komanda, ko vajadzētu izmantot lielākajai daļai integrāciju. Atgriezeniskā izsaukuma funkcija saņem tcData objektu un veiksmes karogu, un tā tiek izsaukta atkārtoti katru reizi, kad mainās piekrišanas stāvoklis. Kopš TCF v2.2 tas ir ieteicamais veids, kā iegūt piekrišanas datus; vecākā komanda getTCData tika atzīta par novecojušu.

removeEventListener

Katrs tcData objekts satur listenerId. Nododiet to funkcijai __tcfapi('removeEventListener', 2, callback, listenerId), kad jūsu skriptam atjauninājumi vairs nav vajadzīgi — piemēram, vienreizējam ielādētājam, kas lēmumu jau ir pieņēmis.

eventStatus nolasīšana

Svarīgākais lauks tcData ir eventStatus. Tam ir trīs vērtības:

• tcloaded — CMP atrada derīgu saglabātu lēmumu, un baneris netiks rādīts. Ar datiem varat rīkoties uzreiz.
• cmpuishown — baneris tiek rādīts. Dati atspoguļo iepriekšējo stāvokli, taču lietotājs var drīz to mainīt.
• useractioncomplete — lietotājs tikko ir izdarījis vai apstiprinājis izvēli. Rīkojieties, balstoties uz jaunajiem datiem.

Tipisks ielādētājs gaida vai nu tcloaded, vai useractioncomplete, un tikai tad pārbauda nolūkus un pārdevējus, kas tam vajadzīgi. Tas ignorē cmpuishown, izņemot, iespējams, lai reģistrētu, ka baneris parādījās.

Nolūku un pārdevēju pārbaude

Objektā tcData piekrišana un leģitīmās intereses tiek atklātas kā objekti, kas indeksēti pēc ID:

• tcData.purpose.consents[1] — piekrišana 1. nolūkam (datu glabāšana ierīcē).
• tcData.purpose.legitimateInterests[7] — leģitīmo interešu statuss 7. nolūkam.
• tcData.vendor.consents[ID] un tcData.vendor.legitimateInterests[ID] — statuss katram pārdevējam, izmantojot pārdevēja ID Global Vendor List.
• tcData.gdprApplies — vai CMP ir noteicis, ka šim apmeklētājam piemērojams GDPR. Ja tas ir false, jūsu skriptam jāseko savai ne-TCF loģikai.
• tcData.tcString — kodētā virkne, ko nododat partneriem, kuri to sagaida.

Pārbaudiet gan nolūku, gan pārdevēju. Nolūka piekrišana bez pārdevēja piekrišanas vai otrādi lielākajai daļai pārdevēju nav pietiekama datu apstrādei.

Iframe un starpkadru izsaukumi

Reklāmas un logrīki bieži darbojas iframe, kuri nevar piekļūt vecāklapas __tcfapi. TCF šo problēmu risina ar postMessage protokolu: CMP augšējai lapai pievieno kadru ar nosaukumu __tcfapiLocator, un kods iframe iekšienē var to atrast, nosūtīt ziņojumu __tcfapiCall un saņemt atbildi __tcfapiReturn. Lielākā daļa reklāmu SDK to jau dara. Ja rakstāt savu iframe kodu, ieviesiet to pašu shēmu, nevis lasiet sīkdatnes starp kadriem.

Biežākās kļūdas un kā tās pamanīt

1. Rīcība pēc cmpuishown. Skripti, kas ielādējas, tiklīdz nostrādā jebkurš atgriezeniskais izsaukums, darbosies, pirms lietotājs ir izlēmis. Filtrējiet pēc eventStatus.
2. Klausītāja noņemšana pārāk agri. Ja to noņemat pēc pirmā atgriezeniskā izsaukuma, palaidīsiet garām vēlāko useractioncomplete un nekad neielādēsities.
3. Atsaukumu ignorēšana. Pastāvīgiem skriptiem jāturpina klausīties un jāapstājas vai jāpārkonfigurējas, kad piekrišana tiek atsaukta.
4. gdprApplies ignorēšana. Ārpus TCF reģioniem nolūku objekti var būt tukši; uzskatīt to par “nav piekrišanas” nozīmē, ka var izslēgt ieņēmumus, kurus jums ir atļauts gūt.
5. Veiksmes karoga nepārbaudīšana. Ja success ir false, reģistrējiet to; tas parasti liecina par bojātu CMP iestatījumu.

Integrācijas testēšana

Pārlūka konsolē izsauciet __tcfapi('ping', 2, console.log), lai pārliecinātos, ka CMP ir klāt, pēc tam reģistrējiet klausītāju ar console.log kā atgriezenisko izsaukumu un izejiet cauri baneram. Pirmajā apmeklējumā jums jāredz cmpuishown, kam seko useractioncomplete, bet pēc pārlādes — tcloaded. Atkārtojiet ar «pieņemt visu», «noraidīt visu» un pielāgotu izvēli un pārliecinieties, ka jūsu skripts katrā gadījumā darbojas pareizi.

Galvenie secinājumi

• Izmantojiet __tcfapi, nevis lasiet CMP sīkdatnes vai aptaujājiet.
• Pārliecinieties, ka CMP stub ielādējas pirms jebkura skripta, kas izsauc API.
• Izmantojiet addEventListener un rīkojieties tikai pēc tcloaded vai useractioncomplete.
• Pārbaudiet gan nolūka, gan pārdevēja statusu un ievērojiet gdprApplies.
• Iframe iekšienē izmantojiet __tcfapiLocator postMessage shēmu.