如何读取 TCF 同意字符串:开发者实战指南
TC string 究竟是什么
IAB Transparency & Consent Framework 生成单一的紧凑令牌 — TC string — 它随每个广告请求一同传递,精确告知供应商用户同意了什么、未同意什么。它采用 Base64-URL 编码并在比特级别打包,所以看起来像乱码(CPxy...AAA),但编码了一条精确、可审计的记录。
各个段落
一个完整的 TC string 是由点分隔的若干段落。第一个是核心字符串;其余为可选:
- 核心 — CMP ID、CMP 版本、同意时间戳、政策版本,以及关键的目的同意和供应商同意位字段。
- 已披露供应商 — 向用户展示了哪些供应商。
- Publisher TC — 针对你(发布商)的特定同意。
位字段是其核心:第 N 位设为 1 表示对目的 N 或供应商 N 的同意。目的 1 是“在设备上存储/访问信息”,目的 3 和 4 涵盖个性化广告,依此类推。
实际解码一个
你很少手动解码比特。请使用 IAB 提供的库或公共解码器:
- 在
.处拆分,并对核心段落进行 Base64-URL 解码。 - 读取固定宽度的头部字段(version、created、lastUpdated、cmpId、cmpVersion)。
- 遍历目的和供应商位字段,以精确查看哪些已被授予。
在 JavaScript 中,__tcfapi('getTCData', 2, cb) 调用返回已解析好的对象 — tcData.purpose.consents 和 tcData.vendor.consents 是 id → boolean 的映射。这是你在运行时的基准事实。
扼杀收入的错误
当个性化需求悄然消失时,通常原因就在 TC string:
- 字符串缺失 — 广告请求未携带
gdprApplies/TC string,因此合规的 SSP 降级为非个性化。 - 供应商未获同意 — 你的需求方合作伙伴的供应商 ID 位为 0,因此无法以个性化方式竞价。
- 过期或陈旧的字符串 — 旧的时间戳会让下游平台不信任它。
- 错误的 CMP ID — 未注册或测试用的 CMP ID 会使整个字符串失效。
一套调试流程
重现用户的同意,从 __tcfapi 或广告请求中抓取实时 TC string,将其通过验证器运行,并将解码出的目的/供应商与你的合作伙伴所要求的进行比对。十有八九,差距就是单个供应商位或一个缺失的目的 1。
FlexyConsent 的定位
FlexyConsent 使用已注册的 CMP ID 生成符合规范的 TC string,保持其新鲜,暴露解码后的状态以供调试,并报告你的流量中实际被授予的目的和供应商 — 让你能看见、而非猜测同意(与收入)在何处流失。
关键要点
- TC string 是每一项同意选择的按位打包、可审计的记录。
- 目的和供应商位字段决定合作伙伴能否投放个性化广告。
- 大多数收入下降可追溯到缺失的字符串、未获同意的供应商,或陈旧/无效的 CMP ID。
- 调试时用
__tcfapi解码实时字符串,并对照合作伙伴要求进行验证。