TikTok Pixel and Events API for Magento Adobe Commerce

Compatible with Magento v2 Adobe Commerce - Open Source (CE), Commerce on-prem (EE), and Commerce on Cloud (ECE)!

(For Magento v1 - Open Source (CE), Commerce on-prem (EE), and OpenMage LTS compatible version go to TikTok Pixel and Events API for Magento 1 OpenMage)

Add TikTok Pixel and TikTok Events API (TikTok Conversions API / TikTok Server-Side API) With Developer Mode To Magento With Just A Few Clicks!

Works great with Catalog Product Feed!

The TikTok Pixel is a piece of JavaScript code for your website that enables you to measure, optimize and build audiences for your ad campaigns. Using the TikTok Pixel, you can leverage the actions people take on your website across devices to inform more effective TikTok advertising campaigns.

The TikTok Events API (TikTok Conversions API / TikTok Server-Side API) (for web) allows advertisers to send web events from their servers directly to TikTok. Server-side events are linked to a pixel and are processed like browser pixel events. This means that server-side events are used in measurement, reporting, and optimization in the same way as browser pixel events.

Apptrian TikTok Pixel and Events API extension for Magento adds TikTok Pixel with Developer Mode on CMS pages (including the home page), category pages, product pages, catalog search pages, catalog advanced search pages, customer registration page, checkout page (default Magento one but also any other without any coding, only by typing page handle (full action name) into our extension config.), and checkout success page. The extension supports Advanced Matching (if the customer is logged in) and has the ability to add custom parameters.

Optionally TikTok Pixel block can be added to any other Magento page or any other extension page (blogs, form pages, etc.) via our extension config by typing page handle (full action name). The TikTok Pixel allows you to place a single pixel on your entire website to report conversions, build audiences and get rich insights into how people use your website.

Conversion measurement lets you track actions people take after viewing your TikTok Ads across multiple devices, including mobile phones, tablets, and desktop computers. By creating a TikTok Pixel and adding it to the pages of your website where conversions happen, like the checkout page, you will see who converts as a result of your TikTok Ads. The pixel will continue to monitor the actions people take after clicking on your ad. You can see which device they saw the ad on and which device they ultimately converted on.

Compatible with Breeze frontend ("Enable Turbo Feature" option set to "No") without the need for an additional compatibility module. It works out of the box via the convenient Compatibility Mode option in config.

Compatible with Hyvä frontend without the need for an additional compatibility module. It works out of the box via the convenient Compatibility Mode option in config.

Account & Pricing

To use this extension, a free TikTok for Business account is required.

NOTE: TikTok Advertising service is not free; additional charges apply to users running TikTok Ad Campaigns.

Features

TikTok Pixel

• An easy way to enable or disable TikTok Pixel.
• Optimized loading of the base code.
• Advanced Matching (if the customer is logged in).
• Works out of the box just type your TikTok Pixel ID (or comma-separated IDs for multi-pixel setups) in our extension config.
• Option to type page handles (full action names) where you want TikTok Pixel. Using this option TikTok Pixel can be added to any other Magento page or any other extension page (blogs, form pages, etc.).
• Option to enable or disable the TikTok Pixel base code.
• Individual options to enable or disable AddToCart, AddToWishlist, CompleteRegistration, InitiateCheckout, PageView, Purchase, Search, and ViewContent events.
• Option to fire PageView event with other events: CompleteRegistration, InitiateCheckout, Purchase, Search, and ViewContent.
• Options to detect selected SKUs for all product types including bundle, configurable, and grouped products. WARNING! *

* WARNING! TikTok Pixel (browser-side) detection of selected SKUs feature is heavily dependent on the theme you are using and its customization. It is impossible to predict all possible themes and customizations. Because of this detection will not work on every theme. This is why extension default configuration comes with this feature turned off. You can turn it on and try it out. If it is working for you leave it on otherwise, turn it off. If you are a developer you will be pleased to know that everything is conveniently located in code.phtml file. To make it work, in some cases only the adjustment of a few JavaScript selectors is needed in others complete rewrite of the detection code is needed. Because of this, we do not give any warranty for the detection feature, nor it is covered by our support service.

Unlike TikTok Pixel browser-side detection, the TikTok Server-Side detection is not dependent on the theme you are using and its customization. Therefore if you want to use detection, we recommend you server-side detection and events.

TikTok Events API (TikTok Conversions API / TikTok Server-Side API)

• An easy way to enable or disable TikTok Events API (TikTok Conversions API / TikTok Server-Side API).
• Advanced Matching (if the customer is logged in).
• Option to type your TikTok Access Token (or comma-separated Tokens for multi-token setups) in our extension config.
• Option to type your TikTok API Version in our extension config.
• Option to type your Test Event Code in our extension config.
• Option to log server-side fired events in the Magento log file.
• Individual options to enable or disable AddToCart, AddToWishlist, CompleteRegistration, InitiateCheckout, PageView, Purchase, Search, and ViewContent events. * Notice
• Option to fire PageView event with other events: CompleteRegistration, InitiateCheckout, Purchase, Search, and ViewContent.
• Option to move parameters outside contents.
• Options to detect selected SKUs for all product types including bundle, configurable, and grouped products.

* Notice Since version 1.0.0 you can send both the TikTok Pixel event and TikTok Events API event simultaneously. The server-side events are not visible in the TikTok Pixel Helper extension for Chrome. You can see server-side events in your TikTok Business Manager.

Category (Category Page)

• Option to type page handles (full action names) where you want category-related code.
• Option to type the event name you want to use for category tracking.
• Options to add custom parameters to your category-related event with parameters to attributes mapping. Example: content_category=name. The format is simple param1=attribute1|param2=attribute2 TikTok Pixel custom parameter and Magento category attribute are connected by = sign and pairs are separated by | sign.

Product (Product Page - AddToCart, AddToWishlist, ViewContent Events)

• Option to type page handles (full action names) where you want product-related code.
• Option to select SKU you want to use for bundle products. Options: Product SKU as (id), Children SKUs as (id)s, Children SKUs as (id)s and Product SKU as (item_group_id)
• Option for content_type to use product_group instead of product for bundle products.
• Option to select SKU you want to use for configurable products. Options: Product SKU as (id), Child SKU as (id), Child SKU as (id) and Product SKU as (item_group_id)
• Option for content_type to use product_group instead of product for configurable products.
• Option to select SKU you want to use for downloadable products. Options: Product SKU as (id), Product SKU as (id) and Parent SKU as (item_group_id)
• Option to select SKU you want to use for grouped products. Options: Product SKU as (id), Children SKUs as (id)s, Children SKUs as (id)s and Product SKU as (item_group_id)
• Option for content_type to use product_group instead of product for grouped products.
• Option to select SKU you want to use for simple products. Options: Product SKU as (id), Product SKU as (id) and Parent SKU as (item_group_id)
• Option to select SKU you want to use for virtual products. Options: Product SKU as (id), Product SKU as (id) and Parent SKU as (item_group_id)
• Options to add custom parameters to your product-related events with parameters to attributes mapping. Example: content_name=name|content_category=product_category. The format is simple param1=attribute1|param2=attribute2 TikTok Pixel custom parameter and Magento product attribute are connected by = sign and pairs are separated by | sign.

Quote (Checkout Page - InitiateCheckout Event)

• Option to type page handles (full action names) where you want quote-related code.
• Option to select SKU you want to use for bundle products. Options: Product SKU as (id), Children SKUs as (id)s, Children SKUs as (id)s and Product SKU as (item_group_id)
• Option to select SKU you want to use for configurable products. Options: Product SKU as (id), Child SKU as (id), Child SKU as (id) and Product SKU as (item_group_id)
• Option to select SKU you want to use for downloadable products. Options: Product SKU as (id), Product SKU as (id) and Parent SKU as (item_group_id)
• Option to select SKU you want to use for grouped products. Options: Children SKUs as (id)s, Children SKUs as (id)s and Product SKU as (item_group_id)
• Option to select SKU you want to use for simple products. Options: Product SKU as (id), Product SKU as (id) and Parent SKU as (item_group_id)
• Option to select SKU you want to use for virtual products. Options: Product SKU as (id), Product SKU as (id) and Parent SKU as (item_group_id)
• Option to type parameter name if you want to use Magento quote ID.
• Options to add custom parameters to your quote-related event with parameters to attributes mapping. Example: content_name=name|content_category=product_category. The format is simple param1=attribute1|param2=attribute2 TikTok Pixel custom parameter and Magento product attribute are connected by = sign and pairs are separated by | sign.

Order (Checkout Success Page - Purchase Event)

• Option to type page handles (full action names) where you want order-related code.
• Option to select SKU you want to use for bundle products. Options: Product SKU as (id), Children SKUs as (id)s, Children SKUs as (id)s and Product SKU as (item_group_id)
• Option to select SKU you want to use for configurable products. Options: Product SKU as (id), Child SKU as (id), Child SKU as (id) and Product SKU as (item_group_id)
• Option to select SKU you want to use for downloadable products. Options: Product SKU as (id), Product SKU as (id) and Parent SKU as (item_group_id)
• Option to select SKU you want to use for grouped products. Options: Children SKUs as (id)s, Children SKUs as (id)s and Product SKU as (item_group_id)
• Option to select SKU you want to use for simple products. Options: Product SKU as (id), Product SKU as (id) and Parent SKU as (item_group_id)
• Option to select SKU you want to use for virtual products. Options: Product SKU as (id), Product SKU as (id) and Parent SKU as (item_group_id)
• Option to type parameter name if you want to use Magento order ID.
• Option to type parameter name if you want to use Magento order increment ID.
• Option to type parameter name if you want to use Magento quote ID.
• Options to add custom parameters to your order-related event with parameters to attributes mapping. Example: content_name=name|content_category=product_category. The format is simple param1=attribute1|param2=attribute2 TikTok Pixel custom parameter and Magento product attribute are connected by = sign and pairs are separated by | sign.

Search (Search Result Page - Search Event)

• Option to type page handles (full action names) where you want search-related code.
• Option to type the event name you want to use for search tracking.
• Option to type the parameter name you want to use for search tracking.
• Option to type request parameters you want to include for search tracking.

Miscellaneous

• Option to select TikTok product identifier. Magento product SKU (Recommended) or Magento product ID.
• Option for Advanced Matching data mapping. Example: external_id=external_id|email=em|phone_number=ph. The format is simple param1=key1|param2=key2 TikTok parameter and data key are connected by = sign and pairs are separated by | sign. Available customer data keys are: em, ph, fn, ln, ge, db, ct, st, zp, country, external_id.
• Option to enable or disable Limited Data Use (LDU).
• Option to enable or disable page method call.
• Option to type the PageView event alternative. The PageView event does not exist in Events API.
• Option to enable or disable page method call for CMS pages, blog pages, etc.
• Options to connect default Magento "Cookie Restriction Mode" cookie or any third-party cookie consent extension or theme customization via following options: Enable Cookie Consent, Consent Cookie Name, Consent Cookie Key, Consent Cookie Value, and Consent Button.
• Option to select Compatibility Mode depending on which frontend you are using. (Official Magento Adobe Commerce, Breeze*, or Hyvä)

* Breeze frontend works only if the "Enable Turbo Feature" option is set to "No".

Installation Instructions

There are several ways you can install any Magento extension. Our extension is no different. We will show you four ways to install the extension, but you must not mix them. Choose one and stick to it.

If you do not know how to install an extension or you wish a professional to do it for you, we offer additional installation service for a small fee.

Installation via file uploading
(If you purchased the extension on our site)

If you purchased the extension on our site then unpack .zip file from /Magento2/InstallByUploadingFiles/ directory inside your Magento root.
- Run following commands on Magento root directory:

php bin/magento maintenance:enable

php bin/magento module:enable --clear-static-content Apptrian_TikTokPixelApi

php bin/magento setup:upgrade

php bin/magento cache:flush

php bin/magento setup:static-content:deploy

php bin/magento maintenance:disable

php bin/magento cache:flush

Installation via Composer
(If you purchased the extension on our site)

If you purchased the extension on our site and you want to install the extension via composer public and private keys. (To find your public and private keys, login to your Apptrian.com customer account and look at the My Downloadable Products section.)
- Run following commands on Magento root directory:

php bin/magento maintenance:enable

composer config --auth http-basic.packages.apptrian.com $PUBLIC_KEY $PRIVATE_KEY

composer config repositories.apptrian-tiktok-pixel-and-events-api composer https://packages.apptrian.com/tiktok-pixel-and-events-api/

composer require apptrian/tiktok-pixel-and-events-api

php bin/magento module:enable --clear-static-content Apptrian_TikTokPixelApi

php bin/magento setup:upgrade

php bin/magento cache:flush

php bin/magento setup:static-content:deploy

php bin/magento maintenance:disable

php bin/magento cache:flush

Installation via Composer by using artifact
(If you purchased the extension on our site)

If you purchased the extension on our site then copy .zip file from /Magento2/InstallWithComposer/ directory inside your MAGENTO_ROOT/vendor/apptrian/packages/ directory (create directory if does not exist).
- Run following commands on Magento root directory:

php bin/magento maintenance:enable

composer config repositories.apptrianartifacts artifact $(pwd)/vendor/apptrian/packages

composer require apptrian/tiktok-pixel-and-events-api

php bin/magento module:enable --clear-static-content Apptrian_TikTokPixelApi

php bin/magento setup:upgrade

php bin/magento cache:flush

php bin/magento setup:static-content:deploy

php bin/magento maintenance:disable

php bin/magento cache:flush

Installation via Composer
(If you purchased the extension on Magento Marketplace)

If you purchased the extension on Magento Marketplace then you must use Composer. Magento Marketplace does not allow extension downloads.
- Run following commands on Magento root directory:

php bin/magento maintenance:enable

composer require apptrian/tiktok-pixel-and-events-api

php bin/magento module:enable --clear-static-content Apptrian_TikTokPixelApi

php bin/magento setup:upgrade

php bin/magento cache:flush

php bin/magento setup:static-content:deploy

php bin/magento maintenance:disable

php bin/magento cache:flush

Please make sure your Magento public and private keys are in your Magento root auth.json file. Usually, people install Magento with one Magento Marketplace account (public and private keys) and then purchase an extension with another Magento Marketplace account (different public and private keys). Check the Magento Marketplace account you used to purchase the extension and make sure its public and private keys are in the Magento root auth.json file. WARNING! if you already have keys there, be very careful because maybe some other extensions are purchased with another Magento Marketplace account.

Configuration

Our extension works out of the box. The only thing you need to do is type your TikTok Pixel ID and Access Token in our extension configuration. To do this, log in to your Magento Admin and go to:

Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > TikTok Pixel (Browser-Side Settings) > TikTok Pixel ID

Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > TikTok Events API (Server-Side Settings) > TikTok Access Token

See FAQ on how to get Access Token.

If you are using a third-party frontend instead of the official Magento Adobe Commerce one, please select it.

Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > Miscellaneous > Compatibility Mode

All options are self-explanatory and have comments and tooltips. Make sure you read them.

After changing options, make sure you refresh your Magento cache.

WARNING! You need to remove all other implementations of TikTok Pixel and use only our extension.

• Remove all other extensions that fire TikTok Pixel.
• Remove all theme customizations that fire TikTok Pixel.
• If you are using GTM (Google Tag Manager), make sure it is not firing TikTok Pixel events.

FAQ

Q: After I replaced the old TikTok Pixel and Events API v1.x.x with the new TikTok Pixel and Events API v2.x.x, my Events Manager does not show any new events, and it seems the new extension does not work?
A: If you replaced any previous version with version 2.0.0 or newer, please paste your TikTok Pixel ID, and TikTok Access Token into the new extension config.
Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > TikTok Pixel (Browser-Side Settings) > TikTok Pixel ID
Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > TikTok Events API (Server-Side Settings) > TikTok Access Token

Q: How do I get TikTok Access Token?
A: The TikTok Ads Manager account Admin or Operator can generate an access token directly under the pixel Settings tab.
- In TikTok Ads Manager, navigate to Assets > Events, and click Manage in the Web Events section.
- Find the pixel object that you want to use for reporting events, and click its name to view its settings. If you need to create a new pixel object, remember to select Manually install pixel code and Developer Mode.
- In the Settings tab, click Generate Access Token. The token will be generated immediately. You can then copy the access token and paste it into our extension config.

Q: TikTok Events API does not work?
A: TikTok deprecated older versions of the Server-Side API. Go to our extension config and for the TikTok API Version option type v1.3 or newer, then refresh your Magento cache (System > Cache Management) and you are done.

Q: Is it possible to add the TikTok Pixel to other Magento pages or extension pages?
A: Yes it is. In our extension config just use the option "Add TikTok Pixel To" and type your page handle (full action name). For example, if you want to add TikTok Pixel to a blog page and that blog page handle is "blog_post_view", you would type this into "Add TikTok Pixel To" at the end. Page handle depends on a particular extension this is just an example. Do not forget to Refresh your Magento Cache.

Q: The TikTok Business Manager reports the issue: "Invalid phone number format"?
A: This means the phone number provided by your customer does not follow the E.164 format. The E.164 format means the phone number must include: country code, city/mobile carrier code without a leading zero, and phone number. Our extension will do filtering of the phone number. That means it will strip all the white space and special characters and use only digits. Also, it will add plus sign at the beginning of the number if needed, as the E.164 format requires. However, our extension will not validate the phone number. That means it will not add missing country codes, or city/mobile carrier codes, and will not check for leading zero. It would be extremely inefficient to validate phone numbers with every event. The phone number should be entered correctly during customer account creation. The simplest way to improve phone number correctness is to use Magento translation to inform the customer on the account creation form that the phone number must include country code and city/mobile carrier code without a leading zero. A better way would be to use JavaScript to validate the phone number while the customer is typing it. There are also JavaScript libraries that can be used to validate the phone number.

Q: Why is the Advanced Matching score low?
A: Some events like ViewContent have a very low score because anyone can access Product pages. On the other hand, the Purchase event has a high score because the customer is logged in, or if it is a guest customer, the data is read from the order billing/shipping address. In short, this is normal. 1. If a customer is not logged in or it is a visitor that does not have an account on your site only IP address, browser Info, ttp, and/or callback/ttclid (if exists) will be sent for Advanced Matching. 2. If a customer is logged in to your Magento store beside the above-mentioned parameters all other parameters can be sent: email, phone_number, fn, ln, ge, db, ct, st, zp, country, external_id. Of course, all the information is read from the Magento database. If for example, the customer did not provide a phone number, the "phone_number" will not be sent because it is empty. Bottom line is, if information exists in your Magento database it will be sent. 3. The "Purchase" event is different. The customer does not have to be logged in or have an account. The information is read from the order billing/shipping address and everything is sent for Advanced Matching.

Q: Why CompleteRegistration event does not work?
A: If you updated the extension from any previous version to version 1.2.0 or newer in our extension config option "Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > TikTok Pixel (Browser-Side Settings) > Add TikTok Pixel To" replace page handle "customer_account_create" with "customer_account_index".

Q: The TikTok Pixel Helper extension for Chrome shows "The pixel code is not installed between <head> </head> . This could prevent your pixel from loading. Please place the pixel code as early as possible in the webpage, ideally between the <head> </head> tags."?
A: This should be ignored. It is well known best practice that JavaScript should be loaded at the bottom of the page so page content can load without interruption.

Q: The TikTok Pixel Helper extension for Chrome shows "The advanced matching parameter (email/phone number) for one or more of your events is missing. This could impact your ad performance. Check the Advanced Matching parameters displayed to see which parameter is missing. Go to your source code and include the missing parameter."?
A: This should be ignored. For an explanation see FAQs "The TikTok Business Manager reports the issue: Invalid phone number format?" and "Why is the Advanced Matching score low?".

Q: Why the TikTok Pixel Helper extension for Chrome shows all sorts of warnings?
A: The TikTok Pixel Helper extension for Chrome does not understand JavaScript. TikTok Pixel Helper extension for Chrome cannot be used to accurately test TikTok Pixel and is completely useless for testing TikTok Events API. This has nothing to do with our extension nor TikTok Pixel and Events API, it is the behavior of the TikTok Pixel Helper extension for Chrome. In short, this is normal and warnings should be ignored. If you want to see TikTok Pixel events go to TikTok Ads Manager > Assets > Events. As for TikTok Events API If you want to see what is sent to TikTok and what is TikTok's response use: Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > TikTok Events API (Server-Side Settings) > Log Events option. Set it to "Yes" to log events. You will be able to see sent events in var/log/system.log. Turn off logging after you check your events because there is no need to bloat a log file.

Q: The PageView vs. ViewContent?
A: In the official TikTok documentation for TikTok Pixel and TikTok Events API, there is no PageView event. The PageView event you see in the TikTok Pixel Helper extension for Chrome and TikTok Ads Manager comes from a method call ttq.page() and there is none for TikTok Events API. This is far from ideal because you do not have an event for CMS pages, Category pages, Blog pages, etc. If you try to use the ViewContent event it will ask for content_id, content_type, value, currency, etc. Even if you fake these parameter values TikTok Ads Manager will report that content_id is missing from the TikTok Catalog. So you cannot use the ViewContent event for CMS pages, Category pages, Blog pages, etc. Our extension has an option "For PageView Use" so you can type any event you want. Unfortunately, TikTok specification currently does not have the appropriate event for CMS pages, Category pages, Blog pages, etc.

Q: When the add to wishlist is clicked just before customer account registration, the CompleteRegistration event does not work. Why?
A: If you updated the extension from any previous version to version 2.2.3 or newer in our extension config option "Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > TikTok Pixel (Browser-Side Settings) > Add TikTok Pixel To" add page handle "wishlist_index_index".

Q: Is your extension compatible with Cookiebot?
A: Yes, it is compatible with Cookiebot since extension version 2.1.2. To set it up configure our extension like below.
Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > Miscellaneous > Enable Cookie Consent option set to Yes
Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > Miscellaneous > Cookie Name option set to CookieConsent
Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > Miscellaneous > Cookie Key option leave empty
Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > Miscellaneous > Cookie Value option set to marketing:true
Stores > Configuration > Apptrian Extensions > TikTok Pixel and Events API > Miscellaneous > Consent Button option set to .CybotCookiebotDialogBodyButton
The above is just an example. The Cookie Name and the Cookie Value depend on how you set up your Cookiebot.