Cross-Origin Iframe-lərdə Razılıq: __tcfapiLocator və __gppLocator Nümunəsi
Problem: Razılıq Üst Pəncərədə Yaşayır
CMP səhifənizdə, üst səviyyəli pəncərədə işləyir. Reklamınızın böyük hissəsi isə yox. Display kreativlər, rich media, header bidding renderer-ləri və bir çox üçüncü tərəf vidjeti iframe-lərdə, çox vaxt fərqli origin-də işləyir. Cross-origin iframe-dəki kod valideyn səhifədəki funksiyanı birbaşa çağıra bilmir, ona görə sadəcə __tcfapi və ya __gpp çağırıb ziyarətçinin seçimini oxuya bilməz.
IAB çərçivələri bunu kiçik, yaxşı müəyyən edilmiş mesajlaşma konvensiyası ilə həll edir. Frame-lərdə işləyən reklam məhsulları, embed-lər və ya ölçmə skriptləri qurursunuzsa, ya da bunu edən reklam steklərini debaq edirsinizsə, onun dəqiq necə işlədiyini bilməyə dəyər.
Locator Frame
JavaScript API ilə yanaşı, TCF CMP üst səviyyəli səhifəyə __tcfapiLocator adlı boş, görünməz iframe əlavə edir. GPP CMP eyni şeyi __gppLocator adlı frame ilə edir. Bu frame-lərin heç bir məzmunu yoxdur. Onların yeganə işi tapıla bilməkdir: iç-içə hər hansı frame-dəki istənilən skript pəncərə iyerarxiyası ilə yuxarı qalxıb hər səviyyədə həmin adlı frame-in olub-olmadığını yoxlaya bilər.
Frame adları window.frames vasitəsilə origin-lər arasında görünən olduğu üçün, dərin iç-içə cross-origin iframe-dəki skript həmin səhifədə başqa heç nəyə girişi olmadan CMP-ni yerləşdirən pəncərəni tapa bilər.
Frame-dəki Skript CMP-ni Necə Tapır
- Cari pəncərədən başlayın. __tcfapi lokal olaraq mövcuddursa, birbaşa istifadə edin — skript frame-də deyil və ya frame CMP-ni paylaşır.
- Əks halda, yuxarıya doğru dövr edin: cari pəncərənin __tcfapiLocator adlı frame ehtiva edib-etmədiyini yoxlayın; yoxdursa, window.parent-ə keçin və yenidən yoxlayın, üst pəncərədə dayanın.
- Locator tapıldıqda, onu ehtiva edən pəncərə CMP-nin pəncərəsidir. Əlaqə indi postMessage vasitəsilə baş verir.
Hər girişi try/catch-ə alın, çünki bəzi brauzerlər və ya sandbox parametrləri cross-origin xassəyə girişdə xəta atır və window.parent cari pəncərəyə bərabər olduqda dövrü dayandırın.
Mesaj Formatı
TCF üçün frame-dəki skript CMP pəncərəsinə __tcfapiCall xassəsi olan obyekt ehtiva edən mesaj göndərir. Onun içində dörd sahə var:
- command — məsələn getTCData, ping və ya addEventListener;
- parameter — əmrin ehtiyac duyduğu istənilən arqument, ya da null;
- version — API versiyası, TCF v2 üçün 2;
- callId — çağıran tərəfindən yaradılan unikal dəyər.
CMP bu mesajları dinləyir, əmri icra edir və returnValue, success və eyni callId-ni ehtiva edən __tcfapiReturn xassəli obyekti geri göndərir. Çağıran tərəf callId-yə görə gözləyən callback-lərin xəritəsini saxlayır, message event-lərini dinləyir və hər qaytarmanı düzgün callback-ə yönləndirir. GPP eyni nümunəyə __gppCall və __gppReturn ilə əməl edir.
Bir çox inteqrasiya kiçik proxy yazır: frame daxilində çağırışları mesajlara çevirən __tcfapi adlı lokal funksiya. Üst pəncərə üçün yazılmış kod bundan sonra frame daxilində dəyişmədən işləyir.
Frame-lər Arası Event Listener-lər
postMessage vasitəsilə göndərilən addEventListener çağırışı birdəfəlik sorğu deyil. CMP razılıq vəziyyəti hər dəyişdikdə, hamısı eyni callId ilə qaytarma mesajı göndərəcək. Buna görə dispatcher-iniz həmin callback-i ilk cavabdan sonra silmək əvəzinə qeydiyyatda saxlamalıdır. Bunu unutmaq klassik xətadır: frame-dəki skript razılığı bir dəfə oxuyur və sonradan geri çəkilməni heç vaxt hiss etmir.
Təhlükəsizlik Mülahizələri
- Mesajın formasını yoxlayın. Gözlənilən xassəni ehtiva etməyən hər mesajı nəzərə almayın və string payload-ları ehtiyatla təhlil edin, çünki bəzi implementasiyalar obyekt əvəzinə JSON string-ləri göndərir.
- Kor-koranə etibar etməyin. İstənilən səhifə frame-inizə mesaj göndərə bilər. Cavabları autentifikasiya edilmiş məlumat kimi deyil, hörmət edilməli razılıq siqnalları kimi qəbul edin və onların imtiyazlı əməliyyatları işə salmasına heç vaxt icazə verməyin.
- Mümkün olduqda konkret hədəf origin-lərdən istifadə edin. CMP-nin origin-i məlumdursa, bütün origin-lərə deyil, ona göndərin.
Nümunənin Çatmadığı Yerlər
Bəzi reklam mühitləri kreativləri daha sərt izolyasiya edir. SafeFrame konteynerləri, düzgün icazələri olmayan sandbox-lanmış iframe-lər və ayrı sənədlərdə render olunan kreativlər frame ağacında gəzə və ya mesaj ala bilməyə bilər. Bu hallarda razılıq siqnalı adətən açıq şəkildə ötürülməlidir, məsələn, reklam sorğusunda parametrlər kimi və ya ad server-in kreativə verdiyi dəyərlər kimi, məsələn, bir çox reklam teqinin dəstəklədiyi gdpr və gdpr_consent parametrləri.
Debaq Çek-Siyahısı
- Üst pəncərənin DevTools-unda locator frame-lərin Elements panelində mövcud olduğunu təsdiqləyin.
- Konsol kontekstini iframe-ə keçirin və locator-un oradan əlçatan olub-olmadığını yoxlayın.
- Çağırışların və qaytarmaların axdığını təsdiqləmək üçün hər iki pəncərədə daxil olan message event-lərini loglayın.
- Bannerdə razılığı dəyişin və frame-dəki listener-lərin yeniləmə aldığını yoxlayın.
- CMP-ni gec yükləməklə test edin ki, frame daxilindəki kodun dərhal əl çəkmək əvəzinə təkrar cəhd etdiyindən və ya gözlədiyindən əmin olasınız.
Əsas Nəticələr
- Cross-origin frame-lər CMP-yə __tcfapiLocator və __gppLocator frame-ləri vasitəsilə çatır.
- Çağırışlar və qaytarmalar callId ilə uyğunlaşdırılmış __tcfapiCall/__tcfapiReturn və ya GPP ekvivalentləri ilə postMessage istifadə edir.
- Sonrakı razılıq dəyişiklikləri çatsın deyə listener callback-lərini qeydiyyatda saxlayın.
- Hər mesajı yoxlayın və onu etibarlı giriş kimi qəbul etməyin.
- Frame-lər tam izolyasiya olunduğu yerdə razılığı reklam sorğusunda açıq şəkildə ötürün.