Twitter Conversions API tag for sGTM

The Twitter Conversions API allows you to send information from your server directly to Twitter servers, which can be used to measure campaign success.

With Twitter CAPI, you make tracking more secure and accurate. Like Facebook, Twitter allows and recommends using a hybrid method of tracking, web+server. When combining web and server tracking, deduplication is required. To match users in events to Twitter profiles, they use customer data: email and twclid.

This guide will discuss how the Twitter conversion API works and how to set up the Twitter CAPI tag in sGTM.

You need more than just a Twitter pixel ID or API token to identify your Twitter CAPI. Twitter requires additional authentication, which is impossible to implement via sGTM. That is why, for now, the Twitter CAPI tag works only with Stape. Feel free to modify the tag template and implement authentication yourself if needed.

The new Twitter CAPI is not ready for prime time yet and will require 5x more work than “standard” CAPI implementation if you're already familiar with FB or TikTok's APIs. In addition, there are some other complications when using their platform that make things difficult.

You will need a dev account, apply for access to Twitter CAPI, and generate several access tokens. We will elaborate on all these steps later in a blog post. 

To complete this setup, you will need to create a server GTM container and send data from the web to the server GTM container. Here are the configuration guides:

Create or sign in to an X Developer Portal account → click “Get started”.

On the next page, choose “Sign up for free account”, and describe the use cases of Twitter’s data and API.

For our case, it can be something like:

I need to configure data conversions tracking and optimize ad performance on X using X CAPI and server GTM, as this type of configuration ensures precise data tracking. For this setup, I need to request access to the conversions API and generate an access token.

Click “Submit”.

You can request access to the X Conversions API by filling in the form. To complete the form, you will need the App ID. To get it, click on the settings of the Project App on the dashboard.

Copy App ID.

Fill out the form with data on your organization, add App ID, and describe the purpose for using the X Ads API Here is an example:

I request access to the X Ads API as I want to track X Ads conversions accurately, get more precise data, and optimize campaigns accordingly. For the configuration need X Ads API is needed as well as server-side Google Tag Manager.

Submit the form.

1. Add “Twitter Conversions API tag” to the server GTM container.

In the server GTM container, go to the section “Templates” → next to “Tag Templates”, click “Search Gallery” → search for “Twitter Conversions API” → add the tag to your container.

2. Create a new tag.

In the section “Tags,” click “New” → as tag configuration select “Twitter Conversions API” tag.

3. Configure the tag.

3.1 Stape Container API Key - due to the way Twitter Conversion API authentication functions, it can't operate fully on sGTM alone. For this reason, the tag requires Stape hosting to work correctly.

You can find the Stape Container API Key in the Stape admin account. Select the container you use → Container Settings.

3.2 Consumer Key and Consumer Secret - both are required to send requests to the Conversions API. They can be found in the X Developer dashboard → click on the key symbol next to your Project App.

Click “Regenerate” in the section “Consumer Keys”.

Copy the generated keys and paste them into the tag configuration. The first value stands for “Consumer Key” and the second for “Consumer Secret”.

3.3 OAuth Token and OAuth Token Secret can be generated in the same place as Consumer Key and Consumer Secret - in the X dashboard → key symbol next to Project App.

To get them, just click on “Regenerate” in the section “Authentication Tokens”. Use an Access Token that belongs to a user with ads-account rights. Without these permissions, Conversion API calls may be rejected.

3.4 Pixel ID - this is your Twitter ad account's Universal Website Tag (UWT) ID. To find it, go to the Twitter events manager.

To find the Pixel ID, log in to X Business Manager → Tools section of the menu → Events Manager → copy Pixel ID.

3.5 Event ID - after creating a conversion API event in the Twitter events manager, you will find it.

You can create new events in the Events Manager section. 

The Event ID can be found next to each event you create.

3.6 Use HttpOnly cookies - this option forbids JavaScript from accessing the cookie if enabled.

3.7 Server Event Data Override - select to override one of the standard server parameters: conversion time, number of items, currency, value, conversion ID, description, and contents. 

3.8 User Data - add user data: email, phone, or twclid.

3.9. Logs Settings - select if you want to use Stape logs.

4. Add a trigger for a tag.

5. Test events. 

When your event has successfully received conversion events within 12 to 24 hours, the status of the ‘Single event web tag’ should show TRACKING on the Conversion Tracking page of the Ads Manager. It will not impact in-flight campaigns that send conversions via the Conversion API.

Twitter supports event deduplication. Combining web and server tracking requires sending a deduplication key with both web and server events. Use conversion_id to send the deduplication key. Deduplication happens only if events were received within 48 hours. 

To create a server-only event, use the Twitter events manager to create a new event and select Install with Conversions API on the third step. 

Unlike other platforms, Twitter accepts only user email and twclid. When you send an email, it should be hashed with SHA256. Twitter tag automatically hashed user email.

Unfortunately, there is no way to test Twitter server events in real time. If tracking is set up correctly, you should see the status of the ‘Single event web tag’ show tracking upon the Conversion Tracking in the Ads Manager within 12 to 24 hours. 

Twitter CAPI can be a great addition to your server-side tracking stack. Though the authorization process for Twitter CAPI is incredibly complicated for now, other logic works highly similar to FB or TikTok conversion APIs: You can send custom or standard events and use web+server or server tracking only. Twitter asks for user data to match users, but for now, they support only user email and twclid. 

Twitter CAPI has two main downsides: the authentication process and the lack of a real-time testing tool. Because of the verification process, the Twitter tag only works with stape servers for sGTM. If Twitter simplifies the authentication process, the stape team will update the tag to work with GCP. 

This guide will help you familiarize yourself with Twitter CAPI and set it up in sGTM. For more detailed information about Twitter CAPI, check the official documentation.