Zgoda w iframe’ach cross-origin: wzorzec __tcfapiLocator i __gppLocator
Problem: zgoda żyje w oknie najwyższego poziomu
CMP działa na Twojej stronie, w oknie najwyższego poziomu. Duża część Twojej reklamy — nie. Kreacje displayowe, rich media, renderery header biddingu i wiele widżetów stron trzecich działa wewnątrz iframe’ów, często na innym originie. Kod w iframe cross-origin nie może bezpośrednio wywołać funkcji na stronie nadrzędnej, więc nie może po prostu wywołać __tcfapi ani __gpp i odczytać wyboru odwiedzającego.
Frameworki IAB rozwiązują to małą, dobrze zdefiniowaną konwencją komunikatów. Jeśli budujesz produkty reklamowe, embedy lub skrypty pomiarowe działające w ramkach, albo debugujesz stacki reklamowe, które tak działają, warto dokładnie wiedzieć, jak to działa.
Ramka locator
Obok API JavaScript CMP z TCF dodaje do strony najwyższego poziomu pusty, niewidoczny iframe o nazwie __tcfapiLocator. CMP z GPP robi to samo z ramką o nazwie __gppLocator. Te ramki nie niosą treści. Ich jedynym zadaniem jest bycie możliwymi do znalezienia: dowolny skrypt w dowolnej zagnieżdżonej ramce może przejść w górę hierarchii okien i sprawdzić, czy na każdym poziomie istnieje ramka o tej nazwie.
Ponieważ nazwy ramek są widoczne między originami przez window.frames, skrypt w głęboko zagnieżdżonym iframe cross-origin może zlokalizować okno hostujące CMP, nie mając dostępu do niczego innego na tej stronie.
Jak skrypt w ramce znajduje CMP
- Zacznij od bieżącego okna. Jeśli __tcfapi istnieje lokalnie, użyj go bezpośrednio — skrypt nie jest w ramce albo ramka współdzieli CMP.
- W przeciwnym razie pętlą idź w górę: sprawdź, czy bieżące okno zawiera ramkę o nazwie __tcfapiLocator; jeśli nie, przejdź do window.parent i sprawdź ponownie, zatrzymując się na oknie najwyższego poziomu.
- Gdy locator zostanie znaleziony, okno, które go zawiera, jest oknem CMP. Komunikacja odbywa się teraz przez postMessage.
Każdy dostęp opakuj w try/catch, ponieważ niektóre przeglądarki lub ustawienia sandboxa zgłaszają wyjątek przy dostępie do właściwości cross-origin, i zatrzymaj pętlę, gdy window.parent jest równe bieżącemu oknu.
Format komunikatu
W TCF skrypt w ramce wysyła do okna CMP komunikat zawierający obiekt z właściwością __tcfapiCall. Wewnątrz są cztery pola:
- command — na przykład getTCData, ping lub addEventListener;
- parameter — dowolny argument potrzebny poleceniu lub null;
- version — wersja API, 2 dla TCF v2;
- callId — unikalna wartość generowana przez wywołującego.
CMP nasłuchuje tych komunikatów, wykonuje polecenie i odsyła obiekt z właściwością __tcfapiReturn zawierającą returnValue, success oraz to samo callId. Wywołujący trzyma mapę oczekujących callbacków kluczowaną przez callId, nasłuchuje zdarzeń message i kieruje każdą odpowiedź do właściwego callbacka. GPP stosuje ten sam wzorzec z __gppCall i __gppReturn.
Wiele integracji pisze mały proxy: lokalną funkcję o nazwie __tcfapi wewnątrz ramki, która tłumaczy wywołania na komunikaty. Kod napisany dla okna najwyższego poziomu działa wtedy w ramce bez zmian.
Event listenery między ramkami
Wywołanie addEventListener wysłane przez postMessage nie jest jednorazowym żądaniem. CMP wyśle komunikat zwrotny za każdym razem, gdy zmieni się stan zgody, wszystkie z tym samym callId. Twój dispatcher musi więc zachować ten callback zarejestrowany, a nie usuwać go po pierwszej odpowiedzi. Zapomnienie o tym to klasyczny błąd: skrypt w ramce odczytuje zgodę raz i nigdy nie zauważa późniejszego wycofania.
Kwestie bezpieczeństwa
- Waliduj kształt komunikatu. Ignoruj każdy komunikat, który nie zawiera oczekiwanej właściwości, i defensywnie parsuj ładunki tekstowe, ponieważ niektóre implementacje wysyłają ciągi JSON zamiast obiektów.
- Nie ufaj ślepo. Każda strona może wysyłać komunikaty do Twojej ramki. Traktuj odpowiedzi jako sygnały zgody, które należy respektować, a nie jako uwierzytelnione dane, i nigdy nie pozwalaj im uruchamiać uprzywilejowanych działań.
- Używaj konkretnych origin docelowych, gdzie możesz. Gdy origin CMP jest znany, wysyłaj do niego, a nie do wszystkich originów.
Dokąd wzorzec nie sięga
Niektóre środowiska reklamowe izolują kreacje ściślej. Kontenery SafeFrame, iframe’y w sandboxie bez właściwych uprawnień i kreacje renderowane w oddzielnych dokumentach mogą nie być w stanie przejść drzewa ramek ani odbierać komunikatów. W takich przypadkach sygnał zgody zwykle trzeba przekazać jawnie, na przykład jako parametry w żądaniu reklamy lub wartości przekazane kreacji przez ad server, takie jak parametry gdpr i gdpr_consent, które obsługuje wiele tagów reklamowych.
Checklista debugowania
- W DevTools okna najwyższego poziomu potwierdź w panelu Elements, że ramki locator istnieją.
- Przełącz kontekst konsoli na iframe i sprawdź, czy stamtąd locator jest osiągalny.
- Loguj przychodzące zdarzenia message w obu oknach, aby potwierdzić, że wywołania i odpowiedzi płyną.
- Zmień zgodę w banerze i sprawdź, czy listenery w ramkach otrzymują aktualizację.
- Testuj z późno załadowanym CMP, aby upewnić się, że kod w ramce ponawia próbę lub czeka, zamiast od razu się poddawać.
Najważniejsze wnioski
- Ramki cross-origin docierają do CMP przez ramki __tcfapiLocator i __gppLocator.
- Wywołania i odpowiedzi używają postMessage z __tcfapiCall/__tcfapiReturn lub odpowiednikami GPP, parowanymi przez callId.
- Zachowaj zarejestrowane callbacki listenerów, aby późniejsze zmiany zgody docierały.
- Waliduj każdy komunikat i nie traktuj go jako zaufanego wejścia.
- Tam, gdzie ramki są w pełni izolowane, przekaż zgodę jawnie w żądaniu reklamy.