Skip to main content

Privacy & Consent Integration Guide (API V2.0)

This document outlines the technical requirements for handling user privacy, data transparency, and regulatory compliance when integrating the Teads Recommendation API. To ensure monetization eligibility and legal compliance (GDPR, CCPA, etc.), specific parameters must be passed in every request.

1. Compliance Parameters​

The API requires explicit signals to determine how user data can be processed for targeting. These are passed as query string parameters.

ParameterTypeRequirementDescription
api_consentIntegerRecommendedSet to 1 to signal that the host application has obtained user consent for API interaction.
cnsntv2StringRequired (EU)The TCF v2.0 Consent String. This encoded string contains the user's specific preferences regarding data processing purposes and vendors.

2. Technical Data Transmission​

To maintain a privacy-first integration, the following headers must be handled correctly to represent the end-user rather than the server making the request.

  • X-Forwarded-For: You must pass the end-user's masked or full IP address. This is used for geo-compliance (ensuring users in specific regions receive the correct privacy protections) and fraud prevention.
  • User-Agent: Pass the user's raw device string. This helps the engine provide age-appropriate or device-appropriate content without requiring personally identifiable information (PII).

3. Data Flow Transparency​

The integration relies on "Contextual Signals" rather than persistent tracking of individual users. By using the following parameters in the request body, the API provides relevant ads based on the conversation rather than a user profile:

  • keywords: High-intent terms derived from the current session.
  • iabCategories: Standardized industry categories used to filter content types without identifying the user.
  • chat: Free text data used for real-time contextual relevance.

4. Privacy-Safe Tracking​

The tracking pixels provided in the response are designed to measure ad performance while respecting user privacy:

  1. Serve Confirmation (reportServed): A non-identifying signal that content was delivered.
  2. Impression Pixels (pixels): Standard industry counters that notify third-party systems an ad was displayed.
  3. Viewability (on-viewed): A critical signal triggered only when the ad enters the visible viewport. This ensures that "tracking" only occurs when a user actually interacts with/sees the content.

5. Implementation Checklist​

  • Ensure api_consent=1 is passed if your app has a global consent mechanism.
  • Dynamically fetch and append the cnsntv2 string for users in regulated regions.
  • Verify that no PII (emails, names, phone numbers) is accidentally included in the chat or keywords parameters.
  • Trigger on-viewed pixels only upon confirmed visual exposure to the ad unit.