Twitter conversion API tag for sGTM

The Twitter Conversion 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.

In this guide, I will talk about how the Twitter conversion API works and how to set up the Twitter CAPI tag in sGTM. 

How Twitter conversion API worksCopy link to this section

AuthentificationCopy link to this section

Adding only Twitter pixel ID or API token is not enough to identify your Twitter CAPI. Twitter requires additional authentication. This type of authentication is impossible to implement via sGTM. That is why for now, the Twitter CAPI tag works only with the stape. Feel free to modify the tag template and implement authentication by yourself if needed.

It looks like 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. There are also some other complications when using their platform that makes things difficult on top of it all.

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

Event deduplicationCopy link to this section

Twitter supports event deduplication. If you combine web and server tracking, you must send 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, you should use the Twitter events manager to create a new event and select install with Conversion API on the 3rd step. 

Twitter CAPI user parametersCopy link to this section

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.

Twitter CAPI testingCopy link to this section

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’ should show tracking upon the Conversion Tracking in the Ads Manager within 12 to 24 hours. 

Twitter CAPI tag parametersCopy link to this section

Stape Container API Key - find it in the sGTM container setting in your stape account. 

Consumer Key, Consumer Secret, OAuth Token, OAuth Token Secret - you can find it in your Twitter dev account after you’ve created a Twitter app. I will show you how to generate these later.

Pixel ID - Your Twitter ad account's Universal Website Tag (UWT) ID. To find it go to the Twitter events manager. 

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

Use HttpOnly cookies - Forbids JavaScript from accessing the cookie if enabled.

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. 

User Data - add user data: email or twclid.

Logs Settings - select if you want to use stape logs. 

What you need to set up Twitter CAPICopy link to this section

Stape container API keyCopy link to this section

Twitter Conversion API authentication is a complicated process; for now, Twitter CAPI authentication can't be fully functional on sGTM. That is why we handle authentication internally. It means that the Twitter CAPI tag requires Stape hosting. If it is possible in the future to use only sGTM for authentication, we will update this tag to support any hosting. You can find the sGTM container API key inside the container settings. 

Consumer Key and Consumer Secret.Copy link to this section

These two keys can be generated only if you have a Twitter developer account. To receive a Twitter dev account, you need to apply for it and wait around 1-3 days till your application is approved. 

When applying, you need to request Essential Access. Make sure to use the correct Twitter account to apply for dev accounts since it is impossible to change accounts later. 

Create an App using the Project and App section when you receive a dev account. Once done, Consumer Key and Consumer Secret will be generated. 

Twitter ads CAPI access.Copy link to this section

To set up CAPI, it is required to obtain ads API access. Include the correct App ID in the Ads API Application. Select Conversion API in the Ads API Application under “How will you use the Ads API?”

OAuth Token and OAuth Token Secret.Copy link to this section

You can find these two in your ad inside the Twitter dev account.

How to set up Twitter CAPI tag in sGTMCopy link to this section

1. Create and set up a server Google Tag Manager container. 

2. Send data to sGTM. You can use GA4, Webhooks, or Data Tag/Data Client.

3. Download the Twitter Conversion API tag from GitHub. Open the sGTM template section -> click three dots in the top right corner ->  Click import -> upload the tag you recently downloaded from GitHub, and click Save. 

4. Create a new tag and select Twitter Tag. Add the Stape Container API Key. To do so, open sGTM container settings and copy Container API Key.

5. Add Consumer Key, Consumer Secret, OAuth Token, OAuth Token Secret. I’ve described how to generate these values here. 

6. Add Twitter pixel ID and Event ID. You can find these values in the Twitter Events Manager.

7. Add event and user data you want to send to Twitter. And set up a trigger. 

8. Unfortunately, there is no way to test Twitter CAPI in real-time. After the setup, use the Twitter events manager to see if Twitter CAPI events were sent.

Conclusion:Copy link to this section

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. To match users, Twitter asks to send user data, but for now, they support only user email and twclid. 

There are two main downsides of Twitter CAPI: authentication process and no real-time testing tool. Because of the verification process, 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. 

I hope this guide will help you become more familiar with Twitter CAPI and set up Twitter CAPI in sGTM. For more detailed information about Twitter CAPI, check the official documentation. If you need help setting up Twitter CAPI, contact us!