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

  1. 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.
  2. 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.
  3. 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:

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

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

Najważniejsze wnioski

← Blog Czytaj wszystko →