Təlimat15 Okt 2026 | FlexyConsent

__tcfapi Hadisə Dinləyicilərindən İstifadə: Razılığa Həssas Skriptlər üçün Developer Bələdçisi

Skriptləriniz niyə polling yox, dinləmə etməlidir

Razılıqdan asılı olan hər skript — reklam teqi, analitika yükləyicisi, header bidding wrapper — iki şeyi bilməlidir: CMP-nin artıq qərarı varmı və bu qərar nədir. Ümumi səhv səhifə yüklənərkən cookie oxumaq və ya nəsə görünənə qədər CMP-ni taymerlə yoxlamaqdır. Hər iki yanaşma proqnozlaşdırıla bilən şəkildə pozulur: cookie formatı CMP-nin daxili məsələsidir və dəyişə bilər, polling isə ya çox tez işə düşür, ya da gözləməyə vaxt itirir.

IAB TCF məhz bu iş üçün standart JavaScript interfeysi müəyyən edir: __tcfapi funksiyası. Bu bələdçi sizə həqiqətən lazım olan əmrləri, alacağınız hadisələri və produksiyada ən çox rast gəlinən xətaları nəzərdən keçirir.

Stub və növbə

TCF CMP-nin tam CMP skripti yüklənməzdən əvvəl, mümkün qədər erkən səhifəyə kiçik bir stub qoyması gözlənilir. Stub window.__tcfapi-ni müəyyən edir və CMP hazır olmamışdan əvvəl edilən çağırışları növbəyə qoyur. CMP yükləməni bitirdikdə növbəni emal edir və hər çağırışa cavab verir.

Bu, digər skriptlərin __tcfapi-ni dərhal çağırmasını təhlükəsiz edir: stub səhifədə onlardan əvvəl olduğu müddətcə çağırışları itmir. Əgər skript __tcfapi təyin olunmadığı üçün xəta atırsa, stub ya yoxdur, ya da çox gec yüklənir — təkrar cəhdlər əlavə etmək əvəzinə yükləmə ardıcıllığını düzəldin.

Önəmli əmrlər

ping

__tcfapi('ping', 2, callback) istifadəçi qərarını gözləmədən əsas statusu qaytarır. Cavab cmpLoaded, stub, loading, loaded və ya error kimi cmpStatus və visible, hidden və ya disabled olan displayStatus daxil edir. Məlum olduqda gdprApplies-i də bildirir. Diaqnostika üçün və TCF-nin bu ziyarətçi üçün ümumiyyətlə aktual olub-olmadığına qərar vermək üçün istifadə edin.

addEventListener

__tcfapi('addEventListener', 2, callback) əksər inteqrasiyaların istifadə etməli olduğu əmrdir. Callback tcData obyekti və uğur bayrağı alır və razılıq vəziyyəti hər dəyişdikdə yenidən çağırılır. TCF v2.2-dən bəri razılıq məlumatlarını almağın tövsiyə olunan yolu budur; köhnə getTCData əmri köhnəlmiş elan edilib.

removeEventListener

Hər tcData obyekti listenerId daşıyır. Skriptinizə artıq yenilənmələr lazım olmadıqda onu __tcfapi('removeEventListener', 2, callback, listenerId)-ə ötürün — məsələn, qərarını artıq vermiş birdəfəlik yükləyici üçün.

eventStatus-u oxumaq

tcData-dakı əsas sahə eventStatus-dur. Üç dəyəri var:

Tipik yükləyici ya tcloaded, ya da useractioncomplete gözləyir, sonra ehtiyac duyduğu məqsəd və vendorları yoxlayır. cmpuishown-u, bəlkə bannerin göründüyünü loglamaq istisna olmaqla, nəzərə almır.

Məqsəd və vendorların yoxlanması

tcData daxilində razılıq və qanuni maraq ID ilə açarlanmış obyektlər kimi təqdim olunur:

Həm məqsədi, həm vendoru yoxlayın. Vendor razılığı olmadan məqsəd razılığı və ya əksi, əksər vendorların məlumatı emal etməsi üçün kifayət deyil.

Iframe-lər və frame-lərarası çağırışlar

Reklamlar və vidjetlər tez-tez valideyn səhifənin __tcfapi-ni görə bilməyən iframe-lərdə işləyir. TCF bunu postMessage protokolu ilə həll edir: CMP üst səhifəyə __tcfapiLocator adlı frame əlavə edir, iframe daxilindəki kod onu tapa, __tcfapiCall mesajı göndərə və __tcfapiReturn cavabı ala bilər. Əksər reklam SDK-ları bunu artıq edir. Öz iframe kodunuzu yazırsınızsa, frame-lər arasında cookie oxumaq əvəzinə eyni nümunəni tətbiq edin.

Ümumi xətalar və onları necə aşkar etməli

  1. cmpuishown üzərində hərəkət. İstənilən callback işə düşən kimi yüklənən skriptlər istifadəçi qərar verməmişdən əvvəl işləyəcək. eventStatus üzrə filtrləyin.
  2. Dinləyicinin çox tez silinməsi. Onu birinci callback-dən sonra silsəniz, sonrakı useractioncomplete-i qaçıracaq və heç vaxt yüklənməyəcəksiniz.
  3. Geri götürmələrin nəzərə alınmaması. Davamlı skriptlər dinləməyə davam etməli və razılıq geri götürüldükdə dayanmalı və ya yenidən konfiqurasiya olunmalıdır.
  4. gdprApplies-in nəzərə alınmaması. TCF bölgələrindən kənarda məqsəd obyektləri boş ola bilər; bunu «razılıq yoxdur» kimi qəbul etmək qazanmağa haqqınız olan gəliri söndürə bilər.
  5. Uğur bayrağının yoxlanmaması. success false olduqda bunu loglayın; bu, adətən pozulmuş CMP qurğusuna işarə edir.

İnteqrasiyanın sınanması

Brauzer konsolunda CMP-nin mövcudluğunu təsdiqləmək üçün __tcfapi('ping', 2, console.log) çağırın, sonra callback kimi console.log ilə dinləyici qeydiyyatdan keçirin və bannerdən keçin. İlk ziyarətdə cmpuishown və ardınca useractioncomplete, yenidən yükləmədə isə tcloaded görməlisiniz. Hamısını qəbul et, hamısını rədd et və fərdi seçimlə təkrarlayın və skriptinizin hər halda düzgün davrandığını təsdiqləyin.

Əsas nəticələr

← Bloq Hamısını Oxu →