# TikTok Events API

[TikTok for Business](https://www.tiktok.com/business/en) est une plateforme mondiale conçue pour offrir aux marques et aux marketeurs les solutions nécessaires pour être des storytellers créatifs et interagir de manière pertinente avec la communauté TikTok.\
L’API Events de TikTok 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 for Web](https://business-api.tiktok.com/portal/docs?id=1771100865818625) and [Events API for App](https://business-api.tiktok.com/portal/docs?id=1771101111730178) version 2.0.

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

## Fonctionnalités clés

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

* **Structure des events**: notre [Référence des events](https://community.commandersact.com/platform-x/developers/tracking/events-reference) correspond [le one](https://business-api.tiktok.com/portal/docs?rid=959icq5stjr\&id=1771100779668482), ce qui signifie que vos données sont correctement bridgées vers les champs attendus de manière optimisée.
* **Mappings préconfigurés**: le mapping des données pour les destinations basées sur les events 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 datalayer.
* **Prise en charge des données multi-éléments**: les informations incluses dans le [item](https://community.commandersact.com/platform-x/developers/tracking/events-reference#item) array 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 à utiliser 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>Access Token</code></td><td><em><strong><code>Obligatoire</code></strong></em> pour les événements <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">Web events</a>.<br>Votre <a href="https://business-api.tiktok.com/portal/docs?id=1771101130925058">API Access Token</a> 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>Pixel Id</code></td><td><em><strong><code>Obligatoire</code></strong></em> pour les événements <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">Web events</a>.<br>Votre identifiant 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>App Id</code></td><td><em><strong><code>Obligatoire</code></strong></em> pour les événements <a href="https://business-api.tiktok.com/portal/docs?id=1771101111730178">App events</a>.<br>Votre identifiant d’application 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>Test Event Code</code></td><td>Pour <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">Web events</a> uniquement. Cela est utilisé pour 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>Manage (Web Events)</code> ➜ Sélectionnez votre pixel ➜ <code>Test Events (Tab)</code> <strong>[1]</strong></td></tr><tr><td><code>Mapping des events</code></td><td>Modifiez le mappage standard entre les événements TikTok et les vôtres ou ajoutez de nouveaux mappages : les événements personnalisés sont également pris en charge. Plus de détails sur la manière 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>TikTok "ViewContent" Event Mapping</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 l’événement TikTok <mark style="color:bleu;"><code>ViewContent</code></mark> . Voir <a href="#quick-reference">Référence rapide</a> pour plus de détails sur le mappage des événements.</td></tr><tr><td><code>Autodiscovery Event Source</code></td><td>Activez cette option pour définir <code>event_source</code> TikTok en fonction de la valeur fournie dans le champ "Smart Mapping" <code>Experience Type</code> ou dans la propriété standard <code>context.app</code> . Le champ "Smart Mapping" <code>Event Source</code> a priorité sur cette option.</td></tr><tr><td><code>Do Not Lower Case User Id</code></td><td>Lorsqu’elle est activée et que la <code>ID de l’utilisateur</code> (Voir <code>Smart Mapping</code> section) est fournie en texte clair de 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;">`Test Event Code`</mark> ne peut être défini que dans les environnements de test, car TikTok n’enregistrera pas les données provenant des événements en direct lorsque 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 %}

| Events 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.** Pour les web events uniquement. Voir <mark style="color:bleu;">`event_source`</mark> dans [Configuration](#configuration) pour plus de détails.\
> **2.** Pour les app events uniquement. Voir <mark style="color:bleu;">`event_source`</mark> dans [Configuration](#configuration) pour plus de détails.\
> **3.** En fonction de votre sélection pour <mark style="color:bleu;">`TikTok "ViewContent" Event Mapping`</mark> . Voir [Configuration](#configuration) pour plus de détails.\
> **4.** Avec <mark style="color:bleu;">`CompletePayment`</mark> events, vous pouvez tirer parti de l’optimisation basée sur la valeur de TikTok [Value-Based Optimization for Web](https://ads.tiktok.com/help/article?aid=10008856) (VBO Web).
> {% endhint %}

## Mappings des 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 associer les événements des visiteurs du site web aux annonces 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 les données 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 attaché aux URL de la page d’atterrissage 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 rien n’est trouvé, elle tente d’analyser la valeur depuis <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>Pixel Id</code></p><p><code>App Id</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>Test Event Code</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;">`Autodiscovery Event Source`</mark> est activé, si le champ "Smart Mapping" `Experience Type` est défini avec une propriété contenant la valeur `native app` ou l’objet `context.app` possède au moins une propriété, alors celle-ci est définie avec `app` . Le "Smart Mapping" `Event Source` 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 des événements.\
> **3.** Si non fourni, l’horodatage actuel est utilisé.\
> **4.** Obligatoire si vous envoyez des web events à la fois depuis le pixel de navigateur TikTok et depuis cette destination. Utilisé pour la déduplication avec <mark style="color:bleu;">`event_source_id`</mark> and <mark style="color:bleu;">`data[0].event`</mark> . Plus de détails sont disponibles via ce [LIEN](https://ads.tiktok.com/marketing_api/docs?id=1771100965992450).\
> **5.** Si non fourni, le cookie <mark style="color:bleu;">`ttclid`</mark> soit de <mark style="color:bleu;">`context.page.url`</mark> est utilisé.\
> **6.** S’il est fourni en texte clair, il est automatiquement haché avec SHA-256.\
> **7.** Si non fourni, le cookie <mark style="color:bleu;">`_ttp`</mark> est utilisé.\
> **8.** Défini lorsque la propriété "Smart Mapping" <mark style="color:bleu;">`Device Platform`</mark> soit de <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> and <mark style="color:bleu;">`NOT_APPLICABLE`</mark>. Plus de détails sont disponibles via 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;">`Device Platform`</mark> soit de <mark style="color:bleu;">`context.device.type`</mark> est défini avec `Android` (insensible à la casse).\
> **11.** Obligatoire pour les app events.\
> **12.** Numéro de téléphone au format [E.164 format](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> and <mark style="color:bleu;">`product_group`</mark> . Par défaut : <mark style="color:bleu;">`product`</mark> .\
> **16.** Obligatoire pour Video Shopping Ads (VSA).\
> **17.** Défini pour les web events.
> {% endhint %}


---

# Agent Instructions: 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.