# TikTok Events API

[TikTok for Business](https://www.tiktok.com/business/en) est une plateforme mondiale conçue pour fournir aux marques et aux spécialistes du marketing les solutions nécessaires pour être des conteurs créatifs et interagir de manière pertinente avec la communauté TikTok.\
L'API TikTok Events est une intégration server-side qui vous permet de partager directement avec TikTok les événements des visiteurs du site web et de l'application en utilisant leur [Events API pour le Web](https://business-api.tiktok.com/portal/docs?id=1771100865818625) et [Events API pour l'App](https://business-api.tiktok.com/portal/docs?id=1771101111730178) version 2.0.

{% hint style="warning" %}
Le [Events API pour APP](https://business-api.tiktok.com/portal/docs?id=1771101111730178) la prise en charge est actuellement en phase de test bêta.
{% endhint %}

## Fonctionnalités clés

La destination TikTok Events API offre les fonctionnalités clés suivantes :

* **Structure des événements**: notre [Référence des événements](https://community.commandersact.com/platform-x/developers/tracking/events-reference) correspond [celui de TikTok](https://business-api.tiktok.com/portal/docs?rid=959icq5stjr\&id=1771100779668482), ce qui signifie que vos données sont correctement reliées aux champs attendus de manière optimisée.
* **Mappings prédéfinis**: le mapping des données pour les destinations basées sur des événements se fait automatiquement, ce qui simplifie les saisies utilisateur.
* **Hachage automatique**: les informations sont automatiquement hachées conformément aux spécifications du partenaire.
* **Smart Mapping**: le mapping des données peut être réajusté à l'aide des champs définis dans votre data layer.
* **Prise en charge des données multi-item**: les informations incluses dans le [item](https://community.commandersact.com/platform-x/developers/tracking/events-reference#item) le tableau est envoyé à TikTok.
* **Prise en charge du code d'événement de test**: validation en temps réel dans vos environnements de test avec le champ <mark style="color:bleu;">`test_event_code`</mark>.

## Configuration de la destination

Avant de commencer avec cette destination, assurez-vous de pouvoir accéder à [TikTok Ads Manager](https://ads.tiktok.com).

{% hint style="warning" %}
Les événements personnalisés TikTok sont disponibles à des fins de reporting et de création d'audiences. L'optimisation n'est actuellement PAS prise en charge.
{% endhint %}

### Configuration

<table><thead><tr><th width="359">Paramètres</th><th>Description</th></tr></thead><tbody><tr><td><code>Jeton d'accès</code></td><td><em><strong><code>Obligatoire</code></strong></em> pour <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">événements web</a>.<br>Votre <a href="https://business-api.tiktok.com/portal/docs?id=1771101130925058">Jeton d'accès API</a> tel que fourni par TikTok. Plus de détails sont disponibles en suivant ce <a href="https://ads.tiktok.com/gateway/docs/index?identify_key=2b9b4278e47b275f36e7c39a4af4ba067d088e031d5f5fe45d381559ac89ba48&#x26;language=ENGLISH&#x26;doc_id=1727537566862337#item-link-How%20to%20generate%20an%20access%20token">LIEN</a>.</td></tr><tr><td><code>ID du pixel</code></td><td><em><strong><code>Obligatoire</code></strong></em> pour <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">événements web</a>.<br>Votre identifiant de pixel tel que fourni par TikTok. Plus de détails sont disponibles en suivant ce <a href="https://business-api.tiktok.com/portal/docs?id=1771101001228290#item-link-Q2%3A%20Where%20can%20I%20find%20the%20Pixel%20Code%3F">LIEN</a>.</td></tr><tr><td><code>ID de l'App</code></td><td><em><strong><code>Obligatoire</code></strong></em> pour <a href="https://business-api.tiktok.com/portal/docs?id=1771101111730178">événements App</a>.<br>Votre identifiant d'App tel que fourni par TikTok. Plus de détails sont disponibles en suivant ce <a href="https://business-api.tiktok.com/gateway/docs/index?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&#x26;language=ENGLISH&#x26;doc_id=1771101111730178#item-link-Create%20an%20App%20in%20Events%20Manager%20and%20obtain%20an%20access%20token">LIEN</a>.</td></tr><tr><td><code>Code d'événement de test</code></td><td>Pour les <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">événements web</a> uniquement. Cela sert à tester le suivi des événements avant le déploiement en production. Ce code se trouve dans le <a href="https://ads.tiktok.com/">TikTok Ads Manager</a> suivant <code>Assets</code> ➜ <code>Events</code> ➜ <code>Gérer (Web Events)</code> ➜ Sélectionnez votre pixel ➜ <code>Test Events (onglet)</code> <strong>[1]</strong></td></tr><tr><td><code>Mapping d'événements</code></td><td>Modifiez le mapping standard entre les événements TikTok et les vôtres, ou ajoutez de nouveaux mappings : les événements personnalisés sont également pris en charge. Plus de détails sur la façon de configurer des événements web TikTok personnalisés sont disponibles en suivant ce <a href="https://business-api.tiktok.com/portal/docs?id=1740858531237890">LIEN</a>.</td></tr><tr><td><code>Mappage de l'événement TikTok "ViewContent"</code></td><td>Sélectionnez <mark style="color:bleu;"><code>page_view</code></mark>, <mark style="color:bleu;"><code>view_item</code></mark> ou les deux pour envoyer à TikTok <mark style="color:bleu;"><code>ViewContent</code></mark> événement. Voir <a href="#quick-reference">Référence rapide</a> pour plus de détails sur le mappage d'événements.</td></tr><tr><td><code>Source d'événement Autodiscovery</code></td><td>Cochez cette option pour définir TikTok <code>event_source</code> en fonction de la valeur fournie dans le champ "Smart Mapping" <code>Type d'expérience</code> ou dans la propriété standard <code>context.app</code> . Le champ "Smart Mapping" <code>Source d'événement</code> a priorité sur cette option.</td></tr><tr><td><code>Ne pas mettre User ID en minuscules</code></td><td>Lorsque cette option est cochée et que le <code>User Id</code> (Voir <code>Smart Mapping</code> section) est fourni en clair pour test, l'identifiant utilisateur n'est pas forcé en minuscules avant l'application de l'algorithme de hachage SHA256.</td></tr></tbody></table>

{% hint style="info" %}
**1.** Le <mark style="color:bleu;">`Code d'événement de test`</mark> ne peut être défini que dans les environnements de test, car TikTok n'enregistrera pas les données provenant d'événements en direct où ce code est inclus. Plus de détails sont disponibles en suivant ce [LIEN](https://business-api.tiktok.com/portal/docs?id=1771100984456193).
{% endhint %}

## Référence rapide

{% hint style="info" %}
Les événements standard TikTok sont détaillés dans ce [LIEN](https://business-api.tiktok.com/portal/docs?id=1771101186666498).
{% endhint %}

| Événements Commanders Act                                                                                                               | TikTok Events                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `achieve_level`                                                                                                                         | `AchieveLevel` **\[2]**                                                                                              |
| `add_payment_info`                                                                                                                      | `AddPaymentInfo`                                                                                                     |
| `add_to_cart`                                                                                                                           | `AddToCart`                                                                                                          |
| `add_to_wishlist`                                                                                                                       | `AddToWishlist`                                                                                                      |
| `application_approval`                                                                                                                  | `ApplicationApproval` **\[1]**                                                                                       |
| `begin_checkout`                                                                                                                        | `InitiateCheckout` **\[1]**                                                                                          |
| <p><code>click\_button</code></p><p><code>view\_content</code></p>                                                                      | `ViewContent`                                                                                                        |
| `complete_tutorial`                                                                                                                     | `CompleteTutorial` **\[2]**                                                                                          |
| `create_group`                                                                                                                          | `CreateGroup` **\[2]**                                                                                               |
| `create_role`                                                                                                                           | `CreateRole` **\[2]**                                                                                                |
| `customize_product`                                                                                                                     | `CustomizeProduct` **\[1]**                                                                                          |
| `purchase`                                                                                                                              | <p><code>CompletePayment</code> <strong>\[1]\[4]</strong><br><code>Checkout</code> <strong>\[2]</strong></p>         |
| `complete_payment`                                                                                                                      | <p><code>CompletePayment</code> <strong>\[1]\[4]</strong><br><code>Purchase</code> <strong>\[2]</strong></p>         |
| `contact`                                                                                                                               | `Contact` **\[1]**                                                                                                   |
| `download`                                                                                                                              | `Download` **\[1]**                                                                                                  |
| `find_location`                                                                                                                         | `FindLocation` **\[1]**                                                                                              |
| <p><code>submit\_form</code></p><p><code>generate\_lead</code></p>                                                                      | `lead` **\[1]**                                                                                                      |
| `generate_lead`                                                                                                                         | `GenerateLead` **\[2]**                                                                                              |
| `in_app_ad_click`                                                                                                                       | `InAppADClick` **\[2]**                                                                                              |
| `in_app_ad_impr`                                                                                                                        | `InAppAdImpr` **\[2]**                                                                                               |
| `install_app`                                                                                                                           | `InstallApp` **\[2]**                                                                                                |
| `join_group`                                                                                                                            | `JoinGroup` **\[2]**                                                                                                 |
| `launch_app`                                                                                                                            | `LaunchAPP` **\[2]**                                                                                                 |
| `loan_application`                                                                                                                      | `LoanApplication` **\[2]**                                                                                           |
| `loan_approval`                                                                                                                         | `LoanApproval` **\[2]**                                                                                              |
| `loan_disbursal`                                                                                                                        | `LoanDisbursal` **\[2]**                                                                                             |
| `login`                                                                                                                                 | `Login` **\[2]**                                                                                                     |
| <p><code>view\_content</code></p><p><code>page\_view</code><strong>\[3]</strong></p><p><code>view\_item</code><strong>\[3]</strong></p> | `ViewContent`                                                                                                        |
| `rate`                                                                                                                                  | `Rate` **\[2]**                                                                                                      |
| `schedule`                                                                                                                              | `Schedule` **\[1]**                                                                                                  |
| `search`                                                                                                                                | `Search`                                                                                                             |
| `sign_up`                                                                                                                               | <p><code>CompleteRegistration</code> <strong>\[1]</strong></p><p><code>Registration</code> <strong>\[2]</strong></p> |
| `spend_credits`                                                                                                                         | `SpendCredits` **\[2]**                                                                                              |
| `start_trial`                                                                                                                           | `StartTrial`                                                                                                         |
| `submit_application`                                                                                                                    | `SubmitApplication` **\[1]**                                                                                         |
| `subscribe`                                                                                                                             | `Subscribe`                                                                                                          |
| `unlock_achievement`                                                                                                                    | `UnlockAchievement` **\[2]**                                                                                         |

{% hint style="info" %}
**1.** Uniquement pour les événements web. Voir <mark style="color:bleu;">`event_source`</mark> dans [Configuration](#configuration) pour plus de détails.\
**2.** Uniquement pour les événements App. Voir <mark style="color:bleu;">`event_source`</mark> dans [Configuration](#configuration) pour plus de détails.\
**3.** Selon votre sélection pour <mark style="color:bleu;">`Mappage de l'événement TikTok "ViewContent"`</mark> . Voir [Configuration](#configuration) pour plus de détails.\
**4.** Avec <mark style="color:bleu;">`CompletePayment`</mark> les événements, vous pouvez tirer parti de TikTok [Value-Based Optimization for Web](https://ads.tiktok.com/help/article?aid=10008856) (VBO Web).
{% endhint %}

## Mappages de champs

{% hint style="info" %}
Les propriétés peuvent être remappées à l'aide de notre [Smart Mapping](https://doc.commandersact.com/features/destinations/advanced-mapping#smart-mapping) fonctionnalité.\
Le pixel client-side TikTok enregistre un identifiant unique dans le cookie [**\_ttp**](https://business-api.tiktok.com/portal/docs?rid=4eezrhr6lg4\&id=1771100936446977)**,** qui est utilisé pour faire correspondre les événements des visiteurs du site web avec les publicités TikTok. Cette destination commence par récupérer cet identifiant depuis <mark style="color:bleu;">`partners.tiktok.ttp`</mark> . S'il n'est pas présent, elle recherche le cookie mentionné précédemment [**\_ttp**](https://business-api.tiktok.com/portal/docs?rid=4eezrhr6lg4\&id=1771100936446977) et définit TikTok <mark style="color:bleu;">`data.0.user.ttp`</mark> avec la valeur obtenue.\
Le [TikTok Click ID](https://business-api.tiktok.com/portal/docs?rid=4eezrhr6lg4\&id=1771100879787009) est un paramètre de suivi qui est ajouté aux URL de destination de votre annonce. Cette destination vérifie si <mark style="color:bleu;">`partners.tiktok.ttclid`</mark> est défini avec la valeur ttclid. S'il n'est pas présent, elle recherche le cookie <mark style="color:bleu;">ttclid</mark>. Si aucun n'est trouvé, elle tente d'analyser la valeur à partir de <mark style="color:bleu;">`context.page.url`</mark> .
{% endhint %}

<table><thead><tr><th width="330.6685580062746">Propriétés Commanders Act</th><th>TikTok Properties</th></tr></thead><tbody><tr><td><code>partners.tiktok.event_source</code></td><td><code>event_source</code> <strong>[*][1]</strong></td></tr><tr><td><p><code>ID du pixel</code></p><p><code>ID de l'App</code></p></td><td><code>event_source_id</code> <strong>[*]</strong></td></tr><tr><td><code>event_name</code></td><td><code>data.0.event</code> <strong>[*][2]</strong></td></tr><tr><td><code>context.event_timestamp</code></td><td><code>data.0.event_time</code> <strong>[*][3]</strong></td></tr><tr><td><code>id</code></td><td><code>data.0.event_id</code> <strong>[4]</strong></td></tr><tr><td><code>partners.tiktok.ttclid</code></td><td><code>data.0.user.ttclid</code> <strong>[5]</strong></td></tr><tr><td><code>user.id</code></td><td><code>data.0.user.external_id</code> <strong>[6]</strong></td></tr><tr><td><code>partners.tiktok.ttp</code></td><td><code>data.0.user.ttp</code> <strong>[7]</strong></td></tr><tr><td><code>context.page.url</code></td><td><code>data.0.page.url</code></td></tr><tr><td><code>context.page.referrer</code></td><td><code>data.0.page.referrer</code></td></tr><tr><td><code>context.device.advertising_id</code></td><td><code>data.0.user.idfa</code> <strong>[8]</strong></td></tr><tr><td><code>context.device.idfv</code></td><td><code>data.0.user.idfv</code> <strong>[8]</strong></td></tr><tr><td><code>context.device.att_status</code></td><td><code>data.0.user.att_status</code> <strong>[8][9]</strong></td></tr><tr><td><code>context.device.advertising_id</code></td><td><code>data.0.user.gaid</code> <strong>[10]</strong></td></tr><tr><td><code>context.app.namespace</code></td><td><code>data.0.app.app_id</code> <strong>[11]</strong></td></tr><tr><td><code>context.app.name</code></td><td><code>data.0.app.app_name</code></td></tr><tr><td><code>context.app.version</code></td><td><code>data.0.app.app_version</code></td></tr><tr><td><code>user.email</code></td><td><code>data.0.user.email</code> <strong>[6]</strong></td></tr><tr><td><code>user.phone</code></td><td><code>data.0.user.phone</code> <strong>[6][12]</strong></td></tr><tr><td><code>context.device.ip</code></td><td><code>data.0.user.ip</code></td></tr><tr><td><code>context.device.user_agent</code></td><td><code>data.0.user.user_agent</code></td></tr><tr><td><code>context.device.language</code></td><td><code>data.0.user.locale</code> <strong>[13]</strong></td></tr><tr><td><code>partners.tiktok.ldu</code></td><td><code>data.0.limited_data_use</code> <strong>[14]</strong></td></tr><tr><td><code>items.X.content_type</code></td><td><code>data.0.properties.contents.X.content_type</code> <strong>[15]</strong></td></tr><tr><td><code>items.X.id</code></td><td><p><code>data.0.properties.contents.X.content_id</code></p><p><code>data.0.properties.content_ids</code> <strong>[16]</strong></p></td></tr><tr><td><code>items.X.product.price</code></td><td><code>data.0.properties.contents.X.price</code></td></tr><tr><td><code>items.X.quantity</code></td><td><code>data.0.properties.contents.X.quantity</code></td></tr><tr><td><code>items.X.product.name</code></td><td><code>data.0.properties.contents.X.content_name</code></td></tr><tr><td><code>items.X.product.category_1</code></td><td><code>data.0.properties.contents.X.content_category</code></td></tr><tr><td><code>items.X.product.brand</code></td><td><code>data.0.properties.contents.X.brand</code></td></tr><tr><td><code>search_term</code></td><td><code>data.0.properties.search_string</code> <strong>[17]</strong></td></tr><tr><td><code>id</code></td><td><code>data.0.properties.order_id</code> <strong>[17]</strong></td></tr><tr><td><code>partners.tiktok.shop_id</code></td><td><code>data.0.properties.shop_id</code> <strong>[17]</strong></td></tr><tr><td><code>status</code></td><td><code>data.0.properties.status</code> <strong>[17]</strong></td></tr><tr><td><code>content_type</code></td><td><code>data.0.properties.content_type</code> <strong>[17]</strong></td></tr><tr><td><code>currency</code></td><td><code>data.0.properties.currency</code></td></tr><tr><td><code>event_name</code></td><td><code>data.0.properties.description</code></td></tr><tr><td><code>value</code></td><td><code>data.0.properties.value</code></td></tr><tr><td><code>items.length</code></td><td><code>data.0.properties.num_items</code></td></tr><tr><td><code>Code d'événement de test</code></td><td><code>test_event_code</code></td></tr></tbody></table>

{% hint style="info" %}
**\*** Propriété obligatoire.\
**1.** Valeurs prises en charge : <mark style="color:bleu;">`web`</mark> , <mark style="color:bleu;">`app`</mark> , <mark style="color:bleu;">`offline`</mark> , et <mark style="color:bleu;">`crm`</mark> . Lorsque <mark style="color:bleu;">`Source d'événement Autodiscovery`</mark> est cochée, si le champ "Smart Mapping" `Type d'expérience` est défini avec une propriété contenant la valeur `native app` ou l'objet `context.app` contient au moins une propriété, alors celle-ci est définie avec `app` . Le "Smart Mapping" `Source d'événement` a priorité sur la fonctionnalité d'autodiscovery. Valeur par défaut : `web` .\
**2.** Voir [Référence rapide](#quick-reference) pour plus de détails sur le mappage d'événements.\
**3.** Si non fourni, l'horodatage actuel est utilisé.\
**4.** Requis si vous envoyez des événements web à la fois depuis le pixel navigateur TikTok et cette destination. Utilisé pour la déduplication avec <mark style="color:bleu;">`event_source_id`</mark> et <mark style="color:bleu;">`data[0].event`</mark> . Plus de détails sont disponibles en suivant ce [LIEN](https://ads.tiktok.com/marketing_api/docs?id=1771100965992450).\
**5.** Si non fourni, le cookie <mark style="color:bleu;">`ttclid`</mark> ou <mark style="color:bleu;">`context.page.url`</mark> est utilisée.\
**6.** S'il est fourni en clair, il est automatiquement haché avec SHA-256.\
**7.** Si non fourni, le cookie <mark style="color:bleu;">`_ttp`</mark> est utilisée.\
**8.** Défini lorsque la propriété "Smart Mapping" <mark style="color:bleu;">`Plateforme de l'appareil`</mark> ou <mark style="color:bleu;">`context.device.type`</mark> est défini avec `iOS` (insensible à la casse).\
**9.** Valeurs prises en charge : <mark style="color:bleu;">`AUTHORIZED`</mark> , <mark style="color:bleu;">`DENIED`</mark> , <mark style="color:bleu;">`NOT_DETERMINED`</mark> , <mark style="color:bleu;">`RESTRICTED`</mark> et <mark style="color:bleu;">`NOT_APPLICABLE`</mark>. Plus de détails sont disponibles en suivant ce [LIEN](https://business-api.tiktok.com/gateway/docs/index?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b\&language=ENGLISH\&doc_id=1771101111730178#item-link-user%20parameters).\
**10.** Défini lorsque la propriété "Smart Mapping" <mark style="color:bleu;">`Plateforme de l'appareil`</mark> ou <mark style="color:bleu;">`context.device.type`</mark> est défini avec `Android` (insensible à la casse).\
**11.** Requis pour les événements App.\
**12.** Numéro de téléphone au format [E.164](https://www.twilio.com/docs/glossary/what-e164).\
**13.** Voir [Identifiant de langue BCP 47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).\
**14.** Voir [Events API 2.0 - Limited Data Use](https://ads.tiktok.com/marketing_api/docs?id=1771101204435970) pour plus de détails.\
**15.** Valeurs prises en charge : <mark style="color:bleu;">`product`</mark> et <mark style="color:bleu;">`product_group`</mark> . Par défaut : <mark style="color:bleu;">`product`</mark> .\
**16.** Requis pour Video Shopping Ads (VSA).\
**17.** Défini pour les événements web.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.commandersact.com/fr/fonctionnalites/destinations/destinations-catalog/tiktok/tiktok.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.