Çapraz Kökenli Iframe'lerde İzin: __tcfapiLocator ve __gppLocator Kalıbı
Sorun: İzin Üst Pencerede Yaşar
Bir CMP sayfanızda, üst düzey pencerede çalışır. Reklamcılığınızın büyük kısmı çalışmaz. Görüntülü kreatifler, zengin medya, header bidding oluşturucuları ve birçok üçüncü taraf widget'ı, çoğu zaman farklı bir kökende olan iframe'ler içinde çalışır. Çapraz kökenli bir iframe'deki kod, üst sayfadaki bir işlevi doğrudan çağıramaz; bu nedenle basitçe __tcfapi veya __gpp'yi çağırıp ziyaretçinin tercihini okuyamaz.
IAB çerçeveleri bunu küçük ve iyi tanımlanmış bir mesajlaşma kuralıyla çözer. Frame'lerde çalışan reklam ürünleri, gömülü öğeler veya ölçüm komut dosyaları geliştiriyorsanız ya da bunları kullanan reklam yığınlarında hata ayıklıyorsanız, bunun tam olarak nasıl çalıştığını bilmeye değer.
Locator Frame'i
JavaScript API'sinin yanı sıra, bir TCF CMP üst düzey sayfaya __tcfapiLocator adında boş, görünmez bir iframe ekler. Bir GPP CMP aynısını __gppLocator adlı bir frame ile yapar. Bu frame'lerin içeriği yoktur. Tek görevleri bulunabilir olmaktır: iç içe herhangi bir frame'deki herhangi bir komut dosyası pencere hiyerarşisinde yukarı çıkabilir ve her düzeyde bu adda bir frame olup olmadığını kontrol edebilir.
Frame adları window.frames aracılığıyla kökenler arasında görünür olduğundan, derinlemesine iç içe çapraz kökenli bir iframe'deki komut dosyası, o sayfadaki başka hiçbir şeye erişimi olmadan CMP'yi barındıran pencereyi bulabilir.
Çerçeveli Bir Komut Dosyası CMP'yi Nasıl Bulur
- Geçerli pencereyle başlayın. __tcfapi yerelde varsa doğrudan kullanın — komut dosyası bir frame içinde değildir veya frame CMP'yi paylaşıyordur.
- Aksi hâlde yukarı doğru döngü kurun: geçerli pencerenin __tcfapiLocator adlı bir frame içerip içermediğini kontrol edin; içermiyorsa window.parent'a geçin ve tekrar kontrol edin; üst pencerede durun.
- Locator bulunduğunda, onu içeren pencere CMP'nin penceresidir. İletişim artık postMessage aracılığıyla gerçekleşir.
Bazı tarayıcılar veya sandbox ayarları çapraz kökenli özellik erişiminde hata verdiğinden her erişimi try/catch içine alın ve window.parent geçerli pencereye eşit olduğunda döngüyü durdurun.
Mesaj Biçimi
TCF için, çerçeveli komut dosyası CMP penceresine __tcfapiCall özelliği içeren bir nesne içeren bir mesaj gönderir. İçinde dört alan vardır:
- command — örneğin getTCData, ping veya addEventListener;
- parameter — komutun ihtiyaç duyduğu herhangi bir argüman veya null;
- version — API sürümü, TCF v2 için 2;
- callId — çağıran tarafından üretilen benzersiz bir değer.
CMP bu mesajları dinler, komutu çalıştırır ve returnValue, success ve aynı callId'yi içeren bir __tcfapiReturn özelliğine sahip bir nesne geri gönderir. Çağıran, bekleyen callback'lerin callId anahtarlı bir haritasını tutar, message olaylarını dinler ve her dönüşü doğru callback'e iletir. GPP aynı kalıbı __gppCall ve __gppReturn ile izler.
Birçok entegrasyon küçük bir proxy yazar: frame içinde çağrıları mesajlara çeviren __tcfapi adlı yerel bir işlev. Böylece üst pencere için yazılmış kod frame içinde değişmeden çalışır.
Frame'ler Arasında Olay Dinleyicileri
postMessage üzerinden gönderilen bir addEventListener çağrısı tek seferlik bir istek değildir. CMP, izin durumu her değiştiğinde, hepsi aynı callId ile bir dönüş mesajı gönderir. Bu nedenle dağıtıcınız, ilk yanıttan sonra silmek yerine o callback'i kayıtlı tutmalıdır. Bunu unutmak klasik bir hatadır: çerçeveli komut dosyası izni bir kez okur ve daha sonraki bir geri çekmeyi hiç fark etmez.
Güvenlik Değerlendirmeleri
- Mesaj şeklini doğrulayın. Beklenen özelliği içermeyen her mesajı yok sayın ve bazı uygulamalar nesne yerine JSON dizeleri gönderdiğinden dize yüklerini savunmacı biçimde ayrıştırın.
- Körü körüne güvenmeyin. Herhangi bir sayfa frame'inize mesaj gönderebilir. Yanıtları, kimliği doğrulanmış veriler olarak değil uyulması gereken izin sinyalleri olarak ele alın ve ayrıcalıklı eylemleri tetiklemelerine asla izin vermeyin.
- Mümkün olduğunda belirli hedef kökenler kullanın. CMP kökeni biliniyorsa, her kökene değil ona gönderin.
Kalıbın Ulaşmadığı Yerler
Bazı reklam ortamları kreatifleri daha sıkı izole eder. SafeFrame kapsayıcıları, doğru izinler olmadan sandbox'lanmış iframe'ler ve ayrı belgelerde oluşturulan kreatifler frame ağacında gezinemeyebilir veya mesaj alamayabilir. Bu durumlarda izin sinyalinin genellikle açıkça iletilmesi gerekir; örneğin reklam isteğindeki parametreler veya birçok reklam etiketinin desteklediği gdpr ve gdpr_consent parametreleri gibi reklam sunucusunun kreatife verdiği değerler olarak.
Hata Ayıklama Kontrol Listesi
- Üst pencerenin DevTools'unda, Elements panelinde locator frame'lerinin var olduğunu doğrulayın.
- Konsol bağlamını iframe'e geçirin ve locator'a oradan ulaşılıp ulaşılamadığını kontrol edin.
- Çağrıların ve dönüşlerin aktığını doğrulamak için her iki pencerede gelen message olaylarını günlüğe kaydedin.
- Banner'da izni değiştirin ve çerçeveli dinleyicilerin bir güncelleme aldığını doğrulayın.
- Çerçeveli kodun hemen pes etmek yerine yeniden denediğinden veya beklediğinden emin olmak için CMP geç yüklenirken test edin.
Önemli Çıkarımlar
- Çapraz kökenli frame'ler CMP'ye __tcfapiLocator ve __gppLocator frame'leri aracılığıyla ulaşır.
- Çağrılar ve dönüşler, callId ile eşleştirilen __tcfapiCall/__tcfapiReturn veya GPP karşılıklarıyla postMessage kullanır.
- Sonraki izin değişikliklerinin ulaşması için dinleyici callback'lerini kayıtlı tutun.
- Her mesajı doğrulayın ve güvenilir girdi olarak ele almaktan kaçının.
- Frame'lerin tamamen izole olduğu yerlerde, izni reklam isteğinde açıkça iletin.