Consenti

TCF v2.2 Implementation Guide

ℹ️Compliance group: general-privacy-consent — full-flexibility mode for programmatic advertising consent via IAB Europe's TCF framework. Use compliance: { type: 'general-privacy-consent' } in your ConsentiSetup config.

IAB Europe's Transparency and Consent Framework (TCF) v2.2 is the standard for programmatic advertising consent. It is required for CMPs operating in the IAB ecosystem (RTB, DSPs, SSPs).

When you need TCF

TCF is needed if your site uses:

  • Programmatic advertising (RTB / header bidding)
  • Google Ad Manager with EU consent mode
  • Any ad tech vendor registered in the IAB Global Vendor List (GVL)
ℹ️If you only use first-party analytics and your own tools, you do not need TCF.

Enabling TCF mode

ts
createConsenti({
  tcf: {
    enabled: true,
    cmpId: 9999,        // Your CMP ID from IAB registration
    cmpVersion: 1,
  },
})
⚠️You must register as a CMP with IAB Europe before going live. Registration is free. See the IAB Europe website for the registration process.

What Consenti implements

Backend

  • tcf.enabled: true — activates TCF mode
  • Global Vendor List (GVL) is fetched and cached for 7 days
  • tcf_string column is added to consent records
  • POST /consent accepts tcfString in the payload
  • GET /consent/:visitorId returns tcfString when present

TC string format

Consenti uses a simplified base64url-encoded JSON format for TC strings. For full IAB TCF v2.2 binary bitfield compliance, install iabtcf-coreand pre-process the TC string before submitting to the API:

bash
npm install iabtcf-core
ts
import { TCModel, TCString } from '@iabtcf/core'

const model = new TCModel(gvl)
model.cmpId = 9999
model.purposeConsents.set([1, 2, 3])
const tcString = TCString.encode(model)

Frontend (__tcfapi stub)

The __tcfapi stub lives in @consenti/ui and is enabled bycore.tcf: { enabled: true }. It implements the four required commands:

CommandDescription
getTCDataReturns the TC string and consent status
pingReturns CMP status (required for IAB compliance)
addEventListenerRegisters a listener for consent updates
removeEventListenerUnregisters a listener

GVL caching

The GVL is fetched once at startup and refreshed every 7 days. If the fetch fails, the cached version is returned. To force a refresh, restart the server.

Mapping cookies to GVL vendors

In the dashboard Cookie Template Editor, enable the TCF Vendors column toggle. Each cookie row gains a vendor picker that searches the GVL by name. Selecting a vendor auto-fills tcfVendorId and tcfPurposes on the cookie. Only cookies with a tcfVendorId that the visitor granted contribute to the TC string.

Testing

Use the IAB TCF Validator to validate your TC string before going live. The validator checks that your CMP ID is registered and that the TC string is well-formed.

Official references