Before you start
Ensure that you have read the Getting Started with CAPI guide first, to learn more about Teads CAPI and its pre-requisites.
Overview of Requirements:
You must already have Google Analytics 4 (GA4) deployed
Teads Conversions API token or CAPI key, generated in TAM Events Manager
Two containers in Google Tag Manager: Web container and Server container.
A custom domain (same as your domain website) to send data from the GTM client container to the GTM server container (optional but highly recommended to improve the tracking accuracy and performance).
Before sending anything to the production environment, we strongly recommend testing the requests with the “Use testing API” checkbox available in our “Teads Advertiser Conversions API” tag.
Implementation Steps
Set up a Web Container
1. Start by creating a Google Tag:
If you have not done so already, create a New Tag and Select «Google Tag»
Insert your Tag ID (Example: G-8F4S0Y79AY): You can find your Google tag settings within Google Ads, Google Analytics, and Google Tag Manager.
In Configuration settings → Configuration Parameter, insert «server_container_url» for the Parameter and your custom URL to the container server in the Value field.
It is recommended to use the same domain name of your website for the custom URL. Using a custom URL (for «server_container_url») from the same domain name of your website is essential to improve the accuracy / performance of tracking. Moreover it ensures that browsers don’t block or limit the tracking.
Set the trigger by selecting «Initialization - All Pages»
2. Create a Custom HTML Tag to measure user session duration:
Create a Custom HTML tag and copy/paste the following code
Click on Triggering section and select «Initialization - All Pages»
3. Create a Google Analytics 4 (GA4) event tag to track the time spent of visits (timespent)
Enter your Measurement ID, then enter “timespent” in Event Name
Select Custom Event for the trigger
Enter “timespent” in Event name
Click on “Some Custom Events” → Select “Event” > “Equals” > “timespent”
4. Use your existing Google Analytics 4 (GA4) event tags to track conversion events
Create a new tag → Google Analytics: GA4 Events
Insert your Measurement ID
Insert your Event Name (recommended GA4 events here)
Insert the Teads metadata in the «Event Parameters» section using GTM variables:
«name» (required)
«price»
«currency»
Important: we currently can’t support several products for the conversion name. If a user makes a purchase with more than one product, please use a generic conversion name like “Completed Purchase”.
5. Use the relevant existing trigger for the conversion event
Please refer to the dedicated Help Center article to learn more about metadata fields (name, price and currency).
Set up a Server Container
1. Measure Page View events:
Create a new tag → Teads Conversions API (CAPI)
Insert your Teads Conversions API (CAPI) Token, Teads Buyer Pixel ID and select «Page View» action
In the Consent Settings section, the Require ad_storage consent checkbox is enabled by default. Please do not disable this feature; it ensures the tag only triggers when ad_storage consent is granted via Google Consent Mode, maintaining the GDPR compliance of your Teads integration.
Click on the Triggering section and then select «All Pages»
2. Measure Time Spent
Create a new tag → Teads Conversions API
Insert your Teads Conversions API (CAPI) Token, Teads Buyer Pixel ID and select «Page View» action
In the Consent Settings section, the Require ad_storage consent checkbox is enabled by default. Please do not disable this feature; it ensures the tag only triggers when ad_storage consent is granted via Google Consent Mode, maintaining the GDPR compliance of your Teads integration.
Now set up the trigger →, select «Custom Event»
Enter “timespent” in Event Name then save (this event fires on all custom events)
3. Measure conversion
Create a new tag → Teads Conversions API (CAPI)
Set the tag configuration as described below:
Token: Your CAPI Token
Your Teads Buyer Pixel ID
Action: Select «Conversion»
Conversion Type: The conversion you want to measure (eg: Add to cart, Purchase, Lead, etc)
Conversion Parameters (a.k.a. metadata) can be configured to populate with variables:
"name" parameter is required
"price" and "currency" parameters are optional.
In the Consent Settings section, the Require ad_storage consent checkbox is enabled by default. Please do not disable this feature; it ensures the tag only triggers when ad_storage consent is granted via Google Consent Mode, maintaining the GDPR compliance of your Teads integration.
Configure the trigger:
“Client Name” contains “GA4”
“Event Name” contains <name of the appropriate event> (e.g. “add_to_cart”)
Test your CAPI integration
Once you have finalized the configuration of your Teads Conversions API (CAPI) integration, you will be able to test all your events. It is strongly recommended to test your CAPI integration before publishing.
Follow these steps to confirm that the changes work as intended:
1. Test the requests with “Use testing API” checkbox:
Before sending anything to the production environment, we highly recommend testing the requests you are configuring with our provided testing environment.
To access the testing environment, select the “Use testing API” checkbox inside “Advanced options” of the Teads Advertiser Conversions API” tag.
Note that it will not be possible to delete an event if it is received and ingested by our pipeline, so be sure to check everything prior to deployment using the testing environment.
Please note that in testing mode you are limited to testing 1 event per second per API key (token)
2. Click on the preview button In THE sGTM Server container
3. Test your event / conversion in real time
Open a new tab or window
Visit your website and test the event / conversion by triggering the action associated with it (e.g. clicking the add to cart button, completing a form, etc)
4. Confirm that the Server Tag is firing in real time
Go to the sGTM Preview mode. Preview mode allows you to see the event tags, like page view, time spent and/or add to cart, firing in real time.
5. Validate the variables and metadata
Within the Preview mode screen, select the relevant event on the left panel, and select the “Event Data” tab to see all metadata.
Publish your CAPI Integration
Once you have successfully tested your newly created tags, follow these steps to publish your settings in sGTM:
Unselect the “Use testing API” checkboxes in all “Teads Advertiser Conversions API” tags
Click the Submit button in GTM to publish the changes to your website
Teads Conversions API (CAPI) is now published!
Note:
For accurate campaign measurement and attribution, it is mandatory to include the Click ID URL parameter with each server request.
For advertisers using 3rd party click trackers with their TAM creatives, the click ID parameter, a.k.a. auctid, may need to be manually configured to forward as outlined in this article.