Dlaczego Twoje skrypty powinny nasłuchiwać, a nie odpytywać

Każdy skrypt zależny od zgody — tag reklamowy, loader analityki, wrapper header biddingu — musi wiedzieć dwie rzeczy: czy CMP ma już decyzję i jaka ona jest. Częstym błędem jest odczytywanie pliku cookie przy ładowaniu strony albo odpytywanie CMP w pętli czasowej, aż coś się pojawi. Oba podejścia zawodzą w przewidywalny sposób: format cookie jest wewnętrzny dla CMP i może się zmienić, a odpytywanie albo uruchamia się zbyt wcześnie, albo traci czas na oczekiwanie.

IAB TCF definiuje standardowy interfejs JavaScript właśnie do tego zadania: funkcję __tcfapi. Ten poradnik omawia polecenia, których naprawdę potrzebujesz, zdarzenia, które otrzymasz, oraz błędy najczęściej pojawiające się na produkcji.

Stub i kolejka

CMP zgodny z TCF powinien umieścić na stronie mały stub jak najwcześniej, przed załadowaniem pełnego skryptu CMP. Stub definiuje window.__tcfapi i kolejkuje wszystkie wywołania wykonane, zanim CMP będzie gotowy. Gdy CMP skończy się ładować, przetwarza kolejkę i odpowiada na każde wywołanie.

Dzięki temu inne skrypty mogą bezpiecznie wywoływać __tcfapi od razu: jeśli stub jest na stronie przed nimi, ich wywołania nie zostaną utracone. Jeśli skrypt zgłasza błąd, ponieważ __tcfapi jest niezdefiniowane, stub albo go brakuje, albo ładuje się zbyt późno — popraw kolejność ładowania zamiast dodawać ponowne próby.

Polecenia, które mają znaczenie

ping

__tcfapi('ping', 2, callback) zwraca podstawowy status bez czekania na decyzję użytkownika. Odpowiedź zawiera cmpLoaded, cmpStatus taki jak stub, loading, loaded lub error oraz displayStatus o wartości visible, hidden lub disabled. Po ustaleniu raportuje także gdprApplies. Użyj go do diagnostyki i do ustalenia, czy TCF w ogóle dotyczy danego odwiedzającego.

addEventListener

__tcfapi('addEventListener', 2, callback) to polecenie, którego powinna używać większość integracji. Callback otrzymuje obiekt tcData i flagę powodzenia, a jest wywoływany ponownie przy każdej zmianie stanu zgody. Od TCF v2.2 to zalecany sposób pozyskiwania danych o zgodzie; starsze polecenie getTCData zostało uznane za przestarzałe.

removeEventListener

Każdy obiekt tcData zawiera listenerId. Przekaż go do __tcfapi('removeEventListener', 2, callback, listenerId), gdy skrypt nie potrzebuje już aktualizacji — na przykład jednorazowy loader, który już podjął decyzję.

Odczytywanie eventStatus

Kluczowym polem w tcData jest eventStatus. Ma trzy wartości:

• tcloaded — CMP znalazł ważną zapisaną decyzję i baner nie zostanie wyświetlony. Możesz od razu działać na podstawie danych.
• cmpuishown — baner jest wyświetlany. Dane odzwierciedlają ewentualny wcześniejszy stan, ale użytkownik może właśnie chcieć go zmienić.
• useractioncomplete — użytkownik właśnie dokonał lub potwierdził wyboru. Działaj na nowych danych.

Typowy loader czeka na tcloaded lub useractioncomplete, a następnie sprawdza potrzebne mu cele i dostawców. Ignoruje cmpuishown, co najwyżej zapisując w logu, że baner się pojawił.

Sprawdzanie celów i dostawców

W tcData zgoda i uzasadniony interes są udostępniane jako obiekty indeksowane identyfikatorem:

• tcData.purpose.consents[1] — zgoda na cel 1 (przechowywanie na urządzeniu).
• tcData.purpose.legitimateInterests[7] — status uzasadnionego interesu dla celu 7.
• tcData.vendor.consents[ID] i tcData.vendor.legitimateInterests[ID] — status poszczególnych dostawców, z użyciem identyfikatora dostawcy z Global Vendor List.
• tcData.gdprApplies — czy CMP ustalił, że do tego odwiedzającego ma zastosowanie RODO. Jeśli jest to false, skrypt powinien podążać własną logiką spoza TCF.
• tcData.tcString — zakodowany ciąg, który przekazujesz partnerom oczekującym go.

Sprawdzaj zarówno cel, jak i dostawcę. Zgoda na cel bez zgody dostawcy, lub odwrotnie, nie wystarcza większości dostawców do przetwarzania danych.

Ramki iframe i wywołania między ramkami

Reklamy i widżety często działają w ramkach iframe, które nie widzą __tcfapi strony nadrzędnej. TCF rozwiązuje to protokołem postMessage: CMP dodaje do strony głównej ramkę o nazwie __tcfapiLocator, a kod wewnątrz iframe może ją zlokalizować, wysłać komunikat __tcfapiCall i odebrać odpowiedź __tcfapiReturn. Większość SDK reklamowych już to robi. Jeśli piszesz własny kod dla iframe, zastosuj ten sam wzorzec zamiast odczytywać pliki cookie między ramkami.

Typowe błędy i jak je wykryć

1. Działanie na podstawie cmpuishown. Skrypty ładowane zaraz po wywołaniu jakiegokolwiek callbacku uruchomią się, zanim użytkownik zdecyduje. Filtruj po eventStatus.
2. Zbyt wczesne usunięcie nasłuchiwacza. Jeśli usuniesz go po pierwszym callbacku, przegapisz późniejsze useractioncomplete i skrypt nigdy się nie załaduje.
3. Ignorowanie wycofania zgody. Skrypty trwałe powinny nadal nasłuchiwać i zatrzymać się lub zmienić konfigurację po wycofaniu zgody.
4. Ignorowanie gdprApplies. Poza regionami TCF obiekty celów mogą być puste; traktowanie tego jako “brak zgody” może wyłączyć przychody, które wolno Ci zarabiać.
5. Niesprawdzanie flagi powodzenia. Gdy success ma wartość false, zapisz to w logu; zwykle oznacza to uszkodzoną konfigurację CMP.

Testowanie integracji

W konsoli przeglądarki wywołaj __tcfapi('ping', 2, console.log), aby potwierdzić obecność CMP, następnie zarejestruj nasłuchiwacz z console.log jako callbackiem i przeklikaj baner. Przy pierwszej wizycie powinieneś zobaczyć cmpuishown, a po nim useractioncomplete, a po odświeżeniu tcloaded. Powtórz test z akceptacją wszystkiego, odrzuceniem wszystkiego i własnym wyborem i sprawdź, czy skrypt zachowuje się poprawnie w każdym przypadku.

Najważniejsze wnioski

• Używaj __tcfapi zamiast odczytywać pliki cookie CMP lub odpytywać.
• Upewnij się, że stub CMP ładuje się przed każdym skryptem wywołującym API.
• Używaj addEventListener i działaj tylko przy tcloaded lub useractioncomplete.
• Sprawdzaj status zarówno celu, jak i dostawcy oraz respektuj gdprApplies.
• W ramkach iframe stosuj wzorzec postMessage z __tcfapiLocator.