How to configure TikTok Events API Gateway
Important! Before you begin, ensure that TikTok web tracking is already configured on your site, whether it's implemented through a GTM container, embedded directly in the website code, or integrated via a plugin. This setup allows you to use existing web events.
Step-by-step guide to configure TikTok Events API Gateway
Create a TikTok Events API Gateway on Stape
1. Log in to your stape.io account.
2. Open the TikTok Events API Gateway page.
3. Click Create Gateway.
4. Fill in the required fields:
- Gateway name. Enter a descriptive name.
- Admin email. This email will be used to manage your TikTok Events API Gateway and can differ from your Stape account email. It should be unique for each Gateway.
- Servers location. For better performance, select a location closer to your website’s visitors.
Then click Create gateway.
5. Select a subscription plan or click Add card later to activate a 7-day free trial.
6. Wait until the Gateway is verified (the status changes to Running.)
Connect your Pixel
1. Click Finish TikTok Gateway setup.
2. You will be redirected to the login interface of TikTok Gateway. Log in using your credentials.
3. In the Events API Gateway hub, click View details → click Connect Data Source.
4. Choose the account and Pixels you’d like to connect and confirm your choices. You will see the added Pixel on your dashboard.
5. (Recommended) Load TikTok js from your subdomain. This will help you increase the protection of your events from ad blockers.
Click View base code.
Next, follow the instructions on the Install Base Code screen.
6. (Optional) Add new Pixels. You can use a single TikTok Events API Gateway to set up multiple TikTok Pixels. Additionally, Pixels from various TikTok Business Accounts can be connected to the same Events API Gateway, provided you have admin access to all the Pixels.
To do that, once you’ve configured your TikTok Events API Gateway, add new Pixels through the hub interface by clicking Connect data source.
Configure a custom domain
Using a custom domain in your TikTok Events API Gateway is highly recommended. It can improve measurement performance, allowing you to choose the subdomain for the Pixel's communication with the Events API Gateway. To achieve this, you'll need to update the tenant domain to a subdomain of your website.
1. In your TikTok Events API Gateway Hub, click Settings → Set up domain.
2. On the Choose domain screen, enter the requested info:
- Prefix - the subdomain of your custom domain.
- Your domain - your existing domain.
Don’t forget to tick the box next to Before configuring DNS settings… and click Next.
3. On the Configure DNS screen, you will be provided with DNS records that you should add to your DNS provider.
Here’s how to add these records to your DNS provider, using Cloudflare as an example:
3.1. Visit your Cloudflare profile → open the DNS tab in the side menu → open the Records screen → click Add record.
3.2. Enter the DNS records from TikTok Events API Gateway Hub:
- Type - copy the Type parameter, usually CNAME.
- Name - copy the Record name parameter.
- Target - copy the Value parameter.
- Proxy status - make sure to toggle this OFF.
Click Save.
Next, wait until the Waiting status in the TikTok Events API Gateway Hub changes.
Custom subdomain is not verified - what to do
Domain verification can take up to 72 hours, but it usually happens within 30-60 minutes if your DNS records are correct. If it takes more time for you, there may be a problem with your configurations.
1. Open the Google Admin Toolbox service called Dig: https://toolbox.googleapps.com/apps/dig/
2. Enter the subdomain you created for Google Tag Gateway (without https:// or any extra characters). Then, select the record type you want to check.
Using this tool, check your DNS records. There are three main reasons why a subdomain may not verified:
- Missing DNS records - make sure that you added all the records specified in your Gateway on Stape.
- Incorrect DNS records - if all entries exist, check that their values match those in your Gateway.
- Extra DNS records - see that there are no extra DNS records for your TikTok Events API Gateway subdomain, only those provided by Stape. Extra records can interfere with domain verification, so you should remove them.
Testing TikTok Events API Gateway
TikTok Events API Gateway uses web events to route them via the server.
Within 30 minutes of connecting your Pixel to the TikTok Events API Gateway hub, you should notice that the event count is no longer zero, and you should also see the names of the events that have been received.
You can also verify that events are sent correctly to the TikTok Events APIG hub by checking the browser console:
- Open your browser Developer Tools → Network tab and reload the webpage.
- Check that events were sent to your TikTok Events API Gateway URL.
