Bakit Dapat Makinig ang Iyong mga Script, Hindi Mag-poll

Anumang script na umaasa sa pahintulot — isang ad tag, isang analytics loader, isang header bidding wrapper — ay kailangang malaman ang dalawang bagay: kung may desisyon na ba ang CMP, at kung ano ang desisyong iyon. Karaniwang pagkakamali ang magbasa ng cookie sa pag-load ng pahina, o mag-poll sa CMP gamit ang timer hanggang may lumabas. Parehong nasisira ang dalawang paraang ito sa mahuhulaang paraan: panloob sa CMP ang format ng cookie at maaari itong magbago, at ang polling ay maaaring masyadong maaga ang takbo o nag-aaksaya ng oras sa paghihintay.

Tinutukoy ng IAB TCF ang isang karaniwang JavaScript interface para mismo sa gawaing ito: ang function na __tcfapi. Ginagabayan ka ng tutorial na ito sa mga command na talagang kailangan mo, sa mga event na matatanggap mo, at sa mga bug na pinakamadalas lumitaw sa production.

Ang Stub at ang Queue

Inaasahang maglalagay ang isang TCF CMP ng maliit na stub sa pahina nang pinakamaaga hangga't maaari, bago ma-load ang buong CMP script. Dinedefine ng stub ang window.__tcfapi at ini-queue ang anumang tawag na ginawa bago handa ang CMP. Kapag natapos mag-load ang CMP, pinoproseso nito ang queue at sinasagot ang bawat tawag.

Ito ang dahilan kung bakit ligtas para sa ibang mga script na tawagin kaagad ang __tcfapi: basta nasa pahina na ang stub bago sila, hindi nawawala ang kanilang mga tawag. Kung nagka-error ang isang script dahil undefined ang __tcfapi, nawawala ang stub o huli itong naglo-load — ayusin ang pagkakasunod-sunod ng pag-load sa halip na magdagdag ng mga retry.

Ang mga Command na Mahalaga

ping

Ang __tcfapi('ping', 2, callback) ay nagbabalik ng pangunahing status nang hindi naghihintay ng desisyon ng user. Kasama sa tugon ang cmpLoaded, isang cmpStatus gaya ng stub, loading, loaded o error, at isang displayStatus na visible, hidden o disabled. Iniuulat din nito ang gdprApplies kapag alam na. Gamitin ito para sa diagnostics at para magpasya kung may kaugnayan ba ang TCF sa bisitang ito.

addEventListener

Ang __tcfapi('addEventListener', 2, callback) ang command na dapat gamitin ng karamihan sa mga integrasyon. Tumatanggap ang callback ng isang tcData object at isang success flag, at tinatawag itong muli sa tuwing nagbabago ang estado ng pahintulot. Mula sa TCF v2.2, ito ang inirerekomendang paraan para makuha ang data ng pahintulot; ang mas lumang command na getTCData ay na-deprecate na.

removeEventListener

Ang bawat tcData object ay may dalang listenerId. Ipasa ito sa __tcfapi('removeEventListener', 2, callback, listenerId) kapag hindi na kailangan ng iyong script ang mga update — halimbawa, isang one-time loader na nakagawa na ng desisyon.

Pagbasa ng eventStatus

Ang pangunahing field sa tcData ay ang eventStatus. May tatlong halaga:

• tcloaded — nakakita ang CMP ng wastong nakaimbak na desisyon at walang ipapakitang banner. Maaari kang kumilos kaagad sa data.
• cmpuishown — ipinapakita ang banner. Sinasalamin ng data ang anumang naunang estado, ngunit maaaring babaguhin ito ng user.
• useractioncomplete — kagagawa o kakukumpirma lang ng user ng isang pagpili. Kumilos sa bagong data.

Ang tipikal na loader ay naghihintay ng alinman sa tcloaded o useractioncomplete, pagkatapos ay sinusuri ang mga layunin at vendor na kailangan nito. Binabalewala nito ang cmpuishown maliban marahil para itala na lumabas ang isang banner.

Pagsuri ng mga Layunin at Vendor

Sa loob ng tcData, ang pahintulot at lehitimong interes ay inilalantad bilang mga object na naka-key ayon sa ID:

• tcData.purpose.consents[1] — pahintulot para sa Layunin 1 (device storage).
• tcData.purpose.legitimateInterests[7] — status ng lehitimong interes para sa Layunin 7.
• tcData.vendor.consents[ID] at tcData.vendor.legitimateInterests[ID] — status bawat vendor, gamit ang Global Vendor List ID ng vendor.
• tcData.gdprApplies — kung natukoy ng CMP na nalalapat ang GDPR sa bisitang ito. Kung false ito, dapat sundin ng iyong script ang non-TCF na lohika nito.
• tcData.tcString — ang naka-encode na string, na ipinapasa mo sa mga partner na umaasa nito.

Suriin pareho ang layunin at ang vendor. Ang purpose consent na walang vendor consent, o kabaligtaran, ay hindi sapat para sa karamihan ng mga vendor na magproseso ng data.

Mga Iframe at Cross-Frame na Tawag

Madalas tumatakbo ang mga ad at widget sa loob ng mga iframe na hindi nakikita ang __tcfapi ng parent page. Nilulutas ito ng TCF gamit ang postMessage protocol: nagdaragdag ang CMP ng frame na pinangalanang __tcfapiLocator sa top page, at ang code sa loob ng iframe ay maaaring hanapin ito, magpadala ng __tcfapiCall na mensahe at tumanggap ng __tcfapiReturn na tugon. Ginagawa na ito ng karamihan sa mga ad SDK. Kung nagsusulat ka ng sarili mong iframe code, ipatupad ang parehong pattern sa halip na magbasa ng mga cookie sa pagitan ng mga frame.

Mga Karaniwang Bug at Paano Makikita ang mga Ito

1. Pagkilos sa cmpuishown. Ang mga script na naglo-load sa sandaling may anumang callback na pumutok ay tatakbo bago magpasya ang user. I-filter ayon sa eventStatus.
2. Masyadong maagang pag-alis ng listener. Kung aalisin mo ito pagkatapos ng unang callback, mamimiss mo ang huling useractioncomplete at hindi ka kailanman maglo-load.
3. Pagbalewala sa mga pag-withdraw. Dapat patuloy na making ang mga persistent na script at huminto o mag-reconfigure kapag na-withdraw ang pahintulot.
4. Pagbalewala sa gdprApplies. Sa labas ng mga rehiyon ng TCF, maaaring walang laman ang mga purpose object; ang pagturing dito bilang “walang pahintulot” ay maaaring magpatay ng kitang pinapayagan kang kitain.
5. Hindi pagsuri sa success flag. Kapag false ang success, itala ito; kadalasan itong senyales ng sirang CMP setup.

Pagsubok sa Iyong Integrasyon

Sa browser console, tawagin ang __tcfapi('ping', 2, console.log) para kumpirmahing naroon ang CMP, pagkatapos ay magrehistro ng listener na may console.log bilang callback at i-click ang banner. Dapat mong makita ang cmpuishown na sinusundan ng useractioncomplete sa unang pagbisita, at tcloaded sa pag-reload. Ulitin gamit ang accept-all, reject-all at custom na pagpili, at kumpirmahing tama ang kilos ng iyong script sa bawat kaso.

Mga Pangunahing Punto

• Gamitin ang __tcfapi sa halip na magbasa ng mga cookie ng CMP o mag-poll.
• Tiyaking naglo-load ang CMP stub bago ang anumang script na tumatawag sa API.
• Gamitin ang addEventListener at kumilos lamang sa tcloaded o useractioncomplete.
• Suriin ang status ng layunin at ng vendor, at igalang ang gdprApplies.
• Gamitin ang __tcfapiLocator postMessage pattern sa loob ng mga iframe.