Hozzájárulás cross-origin iframe-ekben: a __tcfapiLocator és __gppLocator minta
A probléma: a hozzájárulás a felső ablakban él
A CMP az oldalán, a legfelső szintű ablakban fut. A hirdetései nagy része nem. A display kreatívok, rich media, a header bidding rendererek és sok harmadik fél widgetje iframe-ekben fut, gyakran más originen. A cross-origin iframe-ben lévő kód nem hívhat közvetlenül függvényt a szülőoldalon, így nem tudja egyszerűen meghívni a __tcfapi-t vagy a __gpp-t, hogy kiolvassa a látogató döntését.
Az IAB keretrendszerei ezt egy kicsi, jól definiált üzenetküldési konvencióval oldják meg. Ha keretekben futó hirdetési termékeket, beágyazásokat vagy mérőscripteket épít, vagy ilyeneket futtató hirdetési stackeket hibakeres, érdemes pontosan tudni, hogyan működik.
A locator keret
A JavaScript API mellett a TCF CMP a legfelső szintű oldalhoz hozzáad egy üres, láthatatlan iframe-et __tcfapiLocator névvel. A GPP CMP ugyanezt teszi egy __gppLocator nevű kerettel. A keretek nem hordoznak tartalmat. Egyetlen feladatuk, hogy megtalálhatók legyenek: bármely beágyazott keretben lévő bármely script végigmehet felfelé az ablakhierarchián, és minden szinten ellenőrizheti, létezik-e ilyen nevű keret.
Mivel a keretnevek origineken át láthatók a window.frames révén, egy mélyen beágyazott cross-origin iframe-ben lévő script meg tudja találni a CMP-t hosztoló ablakot anélkül, hogy bármi máshoz hozzáférne azon az oldalon.
Hogyan találja meg a keretezett script a CMP-t
- Kezdje az aktuális ablakkal. Ha a __tcfapi helyben létezik, használja közvetlenül — a script nem keretben van, vagy a keret osztozik a CMP-n.
- Máskülönben lépkedjen felfelé ciklusban: ellenőrizze, hogy az aktuális ablak tartalmaz-e __tcfapiLocator nevű keretet; ha nem, lépjen a window.parent-re, és ellenőrizzen újra, a legfelső ablaknál megállva.
- Amikor a locator megvan, az azt tartalmazó ablak a CMP ablaka. A kommunikáció ezután a postMessage-en keresztül zajlik.
Minden hozzáférést csomagoljon try/catch-be, mert egyes böngészők vagy sandbox-beállítások kivételt dobnak a cross-origin tulajdonság-hozzáférésnél, és állítsa le a ciklust, amikor a window.parent megegyezik az aktuális ablakkal.
Az üzenetformátum
A TCF-nél a keretezett script üzenetet küld a CMP ablakának, amely egy __tcfapiCall tulajdonságú objektumot tartalmaz. Benne négy mező van:
- command — például getTCData, ping vagy addEventListener;
- parameter — a parancs által igényelt argumentum, vagy null;
- version — az API verziója, TCF v2-nél 2;
- callId — a hívó által generált egyedi érték.
A CMP figyeli ezeket az üzeneteket, végrehajtja a parancsot, és visszaküld egy objektumot __tcfapiReturn tulajdonsággal, amely tartalmazza a returnValue-t, a success-t és ugyanazt a callId-t. A hívó térképet tart a függő callbackekről callId szerint, figyeli a message eseményeket, és minden visszatérést a megfelelő callbacknek továbbít. A GPP ugyanezt a mintát követi a __gppCall és __gppReturn tulajdonságokkal.
Sok integráció kis proxyt ír: egy helyi függvényt __tcfapi néven a keretben, amely a hívásokat üzenetekre fordítja. A felső ablakhoz írt kód ekkor változtatás nélkül működik a keretben.
Eseményfigyelők keretek között
A postMessage-en át küldött addEventListener hívás nem egyszeri kérés. A CMP minden alkalommal visszaküld egy üzenetet, amikor a hozzájárulási állapot változik, mindet ugyanazzal a callId-vel. A dispatchernek ezért regisztrálva kell tartania azt a callbacket, nem pedig az első válasz után törölnie. Ennek elfelejtése klasszikus hiba: a keretezett script egyszer olvassa a hozzájárulást, és sosem veszi észre a későbbi visszavonást.
Biztonsági megfontolások
- Ellenőrizze az üzenet alakját. Hagyjon figyelmen kívül minden üzenetet, amely nem tartalmazza a várt tulajdonságot, és a karakterlánc-payloadokat védekezően értelmezze, mivel egyes implementációk objektumok helyett JSON-stringeket küldenek.
- Ne bízzon vakon. Bármely oldal küldhet üzeneteket az Ön keretének. A válaszokat tiszteletben tartandó hozzájárulási jelekként kezelje, nem hitelesített adatként, és soha ne engedje, hogy kiváltsanak privilegizált műveleteket.
- Használjon konkrét célorigint, ahol lehet. Ha a CMP origine ismert, annak küldjön, ne minden originnek.
Ahová a minta nem ér el
Egyes hirdetési környezetek szigorúbban elszigetelik a kreatívokat. A SafeFrame konténerek, a megfelelő engedélyek nélküli sandboxolt iframe-ek és a külön dokumentumokban renderelt kreatívok nem biztos, hogy végig tudnak lépni a keretfán vagy üzeneteket tudnak fogadni. Ilyenkor a hozzájárulási jelet általában kifejezetten át kell adni, például a hirdetéskérés paramétereiként vagy az ad server által a kreatívnak átadott értékekként, mint a gdpr és gdpr_consent paraméterek, amelyeket sok hirdetési tag támogat.
Hibakeresési ellenőrzőlista
- A felső ablak DevToolsában az Elements panelen ellenőrizze, hogy a locator keretek léteznek.
- Váltsa a konzol kontextusát az iframe-re, és ellenőrizze, hogy onnan elérhető-e a locator.
- Naplózza a bejövő message eseményeket mindkét ablakban, hogy megerősítse, a hívások és visszatérések áramlanak.
- Változtassa meg a hozzájárulást a bannerben, és ellenőrizze, hogy a keretezett figyelők frissítést kapnak.
- Tesztelje késve betöltött CMP-vel, hogy a keretezett kód újrapróbálkozzon vagy várjon, ahelyett hogy azonnal feladná.
Legfontosabb tanulságok
- A cross-origin keretek a __tcfapiLocator és __gppLocator keretek révén érik el a CMP-t.
- A hívások és visszatérések postMessage-et használnak a __tcfapiCall/__tcfapiReturn vagy a GPP megfelelői szerint, callId alapján párosítva.
- Tartsa regisztrálva a figyelő callbackeket, hogy a későbbi hozzájárulás-változások megérkezzenek.
- Minden üzenetet ellenőrizzen, és ne kezelje megbízható bemenetként.
- Ahol a keretek teljesen elszigeteltek, a hozzájárulást adja át kifejezetten a hirdetéskérésben.