Betikleriniz Neden Yoklamamalı, Dinlemeli

Onaya bağlı her betik — bir reklam etiketi, bir analitik yükleyicisi, bir header bidding sarmalayıcısı — iki şeyi bilmek zorundadır: CMP'nin henüz bir kararı olup olmadığını ve bu kararın ne olduğunu. Yaygın bir hata, sayfa yüklenirken bir çerezi okumak ya da bir şey görünene kadar CMP'yi bir zamanlayıcıyla yoklamaktır. İki yaklaşım da öngörülebilir biçimlerde bozulur: çerez biçimi CMP'ye özgüdür ve değişebilir; yoklama ise ya çok erken tetiklenir ya da beklerken zaman harcar.

IAB TCF tam da bu iş için standart bir JavaScript arayüzü tanımlar: __tcfapi işlevi. Bu eğitim, gerçekten ihtiyaç duyacağınız komutları, alacağınız olayları ve üretimde en sık görülen hataları adım adım anlatır.

Stub ve Kuyruk

Bir TCF CMP'sinin, tam CMP betiği yüklenmeden önce, sayfaya olabildiğince erken küçük bir stub yerleştirmesi beklenir. Stub, window.__tcfapi işlevini tanımlar ve CMP hazır olmadan yapılan çağrıları kuyruğa alır. CMP yüklenmeyi bitirdiğinde kuyruğu işler ve her çağrıyı yanıtlar.

Diğer betiklerin __tcfapi işlevini hemen çağırmasını güvenli kılan budur: stub onlardan önce sayfada olduğu sürece çağrıları kaybolmaz. Bir betik __tcfapi tanımsız olduğu için hata veriyorsa, stub ya eksiktir ya da çok geç yükleniyordur — yeniden deneme eklemek yerine yükleme sırasını düzeltin.

Önemli Olan Komutlar

ping

__tcfapi('ping', 2, callback), kullanıcı kararını beklemeden temel durumu döndürür. Yanıt cmpLoaded, stub, loading, loaded ya da error gibi bir cmpStatus ve visible, hidden ya da disabled değerlerinden biri olan bir displayStatus içerir. Ayrıca, bilindiğinde gdprApplies değerini bildirir. Tanılama için ve TCF'nin bu ziyaretçi için ilgili olup olmadığına karar vermek için kullanın.

addEventListener

__tcfapi('addEventListener', 2, callback), çoğu entegrasyonun kullanması gereken komuttur. Geri çağrı bir tcData nesnesi ve bir başarı bayrağı alır ve onay durumu her değiştiğinde yeniden çağrılır. TCF v2.2'den beri onay verisini almanın önerilen yolu budur; eski getTCData komutu kullanımdan kaldırılmıştır.

removeEventListener

Her tcData nesnesi bir listenerId taşır. Betiğiniz artık güncellemeye ihtiyaç duymadığında — örneğin kararını çoktan vermiş tek seferlik bir yükleyici — bunu __tcfapi('removeEventListener', 2, callback, listenerId) çağrısına iletin.

eventStatus Değerini Okumak

tcData içindeki anahtar alan eventStatus değeridir. Üç değer vardır:

• tcloaded — CMP geçerli bir kayıtlı karar buldu ve hiçbir banner gösterilmeyecek. Veriyle hemen işlem yapabilirsiniz.
• cmpuishown — banner gösteriliyor. Veri önceki durumu yansıtır, ancak kullanıcı bunu değiştirmek üzere olabilir.
• useractioncomplete — kullanıcı az önce bir tercih yaptı ya da onayladı. Yeni veriyle işlem yapın.

Tipik bir yükleyici tcloaded veya useractioncomplete değerlerinden birini bekler, ardından ihtiyaç duyduğu amaçları ve satıcıları kontrol eder. Bir banner'ın göründüğünü günlüğe yazmak dışında cmpuishown değerini yok sayar.

Amaçları ve Satıcıları Kontrol Etmek

tcData içinde onay ve meşru menfaat, kimliğe göre anahtarlanmış nesneler olarak sunulur:

• tcData.purpose.consents[1] — 1. Amaç (cihaz depolaması) için onay.
• tcData.purpose.legitimateInterests[7] — 7. Amaç için meşru menfaat durumu.
• tcData.vendor.consents[ID] ve tcData.vendor.legitimateInterests[ID] — satıcının Global Vendor List kimliği kullanılarak satıcı başına durum.
• tcData.gdprApplies — CMP'nin GDPR'ın bu ziyaretçi için geçerli olduğunu belirleyip belirlemediği. Değer false ise betiğiniz TCF dışı mantığını izlemelidir.
• tcData.tcString — kodlanmış dize; bunu beklentisi olan ortaklara iletirsiniz.

Hem amacı hem de satıcıyı kontrol edin. Satıcı onayı olmayan bir amaç onayı ya da tersi, çoğu satıcının veri işlemesi için yeterli değildir.

Iframe'ler ve Çerçeveler Arası Çağrılar

Reklamlar ve widget'lar çoğu zaman üst sayfanın __tcfapi işlevini göremeyen iframe'ler içinde çalışır. TCF bunu bir postMessage protokolüyle çözer: CMP üst sayfaya __tcfapiLocator adlı bir çerçeve ekler ve iframe içindeki kod bunu bulabilir, bir __tcfapiCall mesajı gönderebilir ve bir __tcfapiReturn yanıtı alabilir. Çoğu reklam SDK'sı bunu zaten yapar. Kendi iframe kodunuzu yazıyorsanız, çerçeveler arasında çerez okumak yerine aynı deseni uygulayın.

Yaygın Hatalar ve Nasıl Fark Edilirler

1. cmpuishown üzerinde işlem yapmak. Herhangi bir geri çağrı tetiklenir tetiklenmez yüklenen betikler, kullanıcı karar vermeden önce çalışır. eventStatus üzerinden filtreleyin.
2. Dinleyiciyi çok erken kaldırmak. İlk geri çağrıdan sonra kaldırırsanız sonraki useractioncomplete olayını kaçırır ve hiç yüklenmezsiniz.
3. Geri çekmeleri yok saymak. Kalıcı betikler dinlemeye devam etmeli ve onay geri çekildiğinde durmalı ya da kendilerini yeniden yapılandırmalıdır.
4. gdprApplies değerini yok saymak. TCF bölgeleri dışında amaç nesneleri boş olabilir; bunu “onay yok” saymak, kazanmanıza izin verilen geliri kapatabilir.
5. Başarı bayrağını kontrol etmemek. success false olduğunda bunu günlüğe yazın; genellikle bozuk bir CMP kurulumuna işaret eder.

Entegrasyonunuzu Test Etmek

Tarayıcı konsolunda CMP'nin mevcut olduğunu doğrulamak için __tcfapi('ping', 2, console.log) çağırın, ardından geri çağrı olarak console.log ile bir dinleyici kaydedin ve banner'da gezinin. İlk ziyarette cmpuishown ve ardından useractioncomplete, yeniden yüklemede ise tcloaded görmelisiniz. Hepsini kabul et, hepsini reddet ve özel bir seçimle tekrarlayın; betiğinizin her durumda doğru davrandığını doğrulayın.

Önemli Çıkarımlar

• CMP çerezlerini okumak ya da yoklama yapmak yerine __tcfapi kullanın.
• API'yi çağıran herhangi bir betikten önce CMP stub'ının yüklendiğinden emin olun.
• addEventListener kullanın ve yalnızca tcloaded veya useractioncomplete üzerinde işlem yapın.
• Hem amaç hem satıcı durumunu kontrol edin ve gdprApplies değerine saygı gösterin.
• Iframe'lerin içinde __tcfapiLocator postMessage desenini kullanın.