# 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 des solutions pour être des conteurs créatifs et s'engager de manière significative avec la communauté TikTok.\
L'Events API de TikTok est une intégration server-side qui vous permet de partager les événements des visiteurs de sites et d'apps directement avec TikTok en utilisant leur [Events API for Web](https://business-api.tiktok.com/portal/docs?id=1771100865818625) et [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) support est actuellement en phase de beta testing.
{% endhint %}

## Principales fonctionnalités

La destination TikTok Events fournit les principales fonctionnalités suivantes :

* **Structure des événements**: notre [Events reference](https://community.commandersact.com/platform-x/developers/tracking/events-reference) correspond [à celle de TikTok](https://business-api.tiktok.com/portal/docs?rid=959icq5stjr\&id=1771100779668482), ce qui signifie que vos données sont correctement mappées vers les champs attendus de manière optimisée.
* **Mappings préconstruits**: le mapping des données pour les destinations basées sur des événements se fait automatiquement, ce qui simplifie les saisies utilisateur.
* **Hashing automatique**: les informations sont hashées automatiquement conformément aux spécifications du partenaire.
* **Smart mapping**: le mapping des données peut être réajusté en utilisant les champs définis dans votre datalayer.
* **Prise en charge des données multi-articles**: les informations incluses dans le [item](https://community.commandersact.com/platform-x/developers/tracking/events-reference#item) array sont envoyées à TikTok.
* **Prise en charge du test event code**: 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 d'avoir accès à [TikTok Ads Manager](https://ads.tiktok.com).

{% hint style="warning" %}
Les événements personnalisés TikTok sont disponibles pour le reporting et la 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>Requis</code></strong></em> pour <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> 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">LINK</a>.</td></tr><tr><td><code>Pixel Id</code></td><td><em><strong><code>Requis</code></strong></em> pour <a href="https://business-api.tiktok.com/portal/docs?id=1771100865818625">Web events</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">LINK</a>.</td></tr><tr><td><code>App Id</code></td><td><em><strong><code>Requis</code></strong></em> pour <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">LINK</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> seulement. Ceci est utilisé pour tester le suivi des événements avant le déploiement en production. Ce code se trouve dans les <a href="https://ads.tiktok.com/">TikTok Ads Manager</a> éléments suivants <code>Assets</code> ➜ <code>Events</code> ➜ <code>Manage (Web Events)</code> ➜ Sélectionnez votre pixel ➜ <code>Test Events (Onglet)</code> <strong>[1]</strong></td></tr><tr><td><code>Mapping des événements</code></td><td>Modifiez le mapping standard entre les événements de 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 web events personnalisés TikTok sont disponibles en suivant ce <a href="https://business-api.tiktok.com/portal/docs?id=1740858531237890">LINK</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 à TikTok l'événement <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 mapping des événements.</td></tr><tr><td><code>Source d'événement autodécouverte</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>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>Ne pas mettre en minuscules l'User Id</code></td><td>Lorsque cochée et que le <code>User Id</code> (Voir <code>Smart Mapping</code> section) est fourni en clair pour les tests, l'identifiant utilisateur n'est pas forcé en minuscules avant l'application de l'algorithme de hash 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 d'événements live où ce code est inclus. Plus de détails sont disponibles en suivant ce [LINK](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 [LINK](https://business-api.tiktok.com/portal/docs?id=1771101186666498).
{% endhint %}

| Commanders Act Events                                                                                                                   | 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.  \
> \&#xNAN;**\[2]** Pour les app events uniquement. Voir <mark style="color:bleu;">`event_source`</mark> dans [Configuration](#configuration) pour plus de détails.  \
> \&#xNAN;**\[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.  \
> \&#xNAN;**\[4]** Avec <mark style="color:bleu;">`CompletePayment`</mark> events vous pouvez profiter de TikTok [Value-Based Optimization for Web](https://ads.tiktok.com/help/article?aid=10008856) (VBO Web).
> {% endhint %}

## Mappings de champs

{% hint style="info" %}
La plupart des propriétés peuvent être remappées en utilisant notre fonctionnalité "Smart Mapping".\
Le pixel côté client 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 aux 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 précédemment mentionné [**\_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 résultante.\
Le [Tiktok Click ID](https://business-api.tiktok.com/portal/docs?rid=4eezrhr6lg4\&id=1771100879787009) est un paramètre de suivi qui est attaché aux URL de la page 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 depuis <mark style="color:bleu;">`context.page.url`</mark> .
{% endhint %}

<table><thead><tr><th width="330.6685580062746">Propriétés Commanders Act</th><th>Propriétés TikTok</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. \
> \&#xNAN;**\[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 autodécouverte`</mark> est cochée, si le champ "Smart Mapping" `Experience Type` est défini avec une propriété contenant la valeur `native app` ou si l'objet `context.app` a au moins une propriété alors celle-ci est définie avec `app` . Le "Smart Mapping" `Event Source` a priorité sur la fonctionnalité d'autodétection. Valeur par défaut : `web` .  \
> \&#xNAN;**\[2]** Voir [Référence rapide](#quick-reference) pour plus de détails sur le mapping des événements.  \
> \&#xNAN;**\[3]** Si non fourni, l'horodatage courant est utilisé.  \
> \&#xNAN;**\[4]** Requis si vous envoyez des web events à la fois depuis le pixel TikTok côté client et depuis cette destination. Utilisé pour la déduplication conjointement 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 [LINK](https://ads.tiktok.com/marketing_api/docs?id=1771100965992450).  \
> \&#xNAN;**\[5]** Si non fourni, le cookie <mark style="color:bleu;">`ttclid`</mark> ou <mark style="color:bleu;">`context.page.url`</mark> est utilisé.  \
> \&#xNAN;**\[6]** S'il est fourni en clair, il est automatiquement hashé avec SHA-256.  \
> \&#xNAN;**\[7]** Si non fourni, le cookie <mark style="color:bleu;">`_ttp`</mark> est utilisé.  \
> \&#xNAN;**\[8]** Défini lorsque la propriété "Smart Mapping" <mark style="color:bleu;">`Platforme de l'appareil`</mark> ou <mark style="color:bleu;">`context.device.type`</mark> est défini sur `iOS` (insensible à la casse).  \
> \&#xNAN;**\[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 [LINK](https://business-api.tiktok.com/gateway/docs/index?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b\&language=ENGLISH\&doc_id=1771101111730178#item-link-user%20parameters).  \
> \&#xNAN;**\[10]** Défini lorsque la propriété "Smart Mapping" <mark style="color:bleu;">`Platforme de l'appareil`</mark> ou <mark style="color:bleu;">`context.device.type`</mark> est défini sur `Android` (insensible à la casse).  \
> \&#xNAN;**\[11]** Requis pour les app events.  \
> \&#xNAN;**\[12]** Numéro de téléphone au format [E.164 format](https://www.twilio.com/docs/glossary/what-e164).  \
> \&#xNAN;**\[13]** Voir [Identifiant de langue BCP 47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).  \
> \&#xNAN;**\[14]** Voir [Events API 2.0 - Limited Data Use](https://ads.tiktok.com/marketing_api/docs?id=1771101204435970) pour plus de détails.  \
> \&#xNAN;**\[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> .  \
> \&#xNAN;**\[16]** Requis pour les Video Shopping Ads (VSA).  \
> \&#xNAN;**\[17]** Défini pour les web events.
> {% endhint %}