> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.crowdchange.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok

> Ajoutez le Pixel TikTok et l'API Events à CrowdChange pour suivre les pages vues, l'ajout au panier et les dons complétés depuis les pubs TikTok.

## Intégration du Pixel TikTok

CrowdChange prend en charge le suivi par Pixel TikTok côté navigateur ainsi que le suivi des achats optionnel via l'API Events de TikTok.

Une fois connecté, votre Pixel TikTok reçoit les événements page, `AddToCart` et `CompletePayment`.

Si un jeton d'accès à l'API Events de TikTok est configuré, CrowdChange envoie également les paiements complétés depuis le serveur.

***

## Configuration

1. Accédez à **Admin -> Paramètres de mise en page -> Meta et analytique**
2. Faites défiler jusqu'à la section **Pixel TikTok**
3. Entrez votre **ID de Pixel TikTok**, par exemple `CXXXXXXXXXXXXXXX`
4. Facultatif : entrez votre **jeton d'accès à l'API Events de TikTok**
5. Cliquez sur **Enregistrer**

Le fragment de code du Pixel pour le navigateur est automatiquement injecté dans chaque page une fois l'ID de Pixel enregistré. Les jetons de l'API Events sont stockés sous forme de valeurs chiffrées en écriture seule; laissez le champ du jeton vide pour conserver un jeton existant.

***

## Événements suivis

### Page

Déclenché automatiquement au chargement de la page et lors de la navigation virtuelle entre les pages.

```javascript theme={null}
ttq.page();
```

***

### AddToCart

Déclenché lorsqu'un article est ajouté au panier de paiement.

| Paramètre  | Type       | Description                                       |
| ---------- | ---------- | ------------------------------------------------- |
| `currency` | `string`   | Code de devise ISO 4217, par exemple `USD`, `CAD` |
| `value`    | `number`   | Valeur totale de la charge utile de l'article     |
| `contents` | `object[]` | Charges utiles de contenu TikTok                  |

**Exemple de charge utile**

```json theme={null}
{
  "currency": "CAD",
  "value": 50,
  "contents": [
    {
      "content_id": "registration",
      "content_name": "Registration",
      "content_category": "registration",
      "price": 50,
      "quantity": 1
    }
  ]
}
```

***

### CompletePayment

Déclenché lorsqu'un donateur complète avec succès une transaction.

| Paramètre  | Type       | Description                                                 |
| ---------- | ---------- | ----------------------------------------------------------- |
| `currency` | `string`   | Code de devise ISO 4217                                     |
| `value`    | `number`   | Montant total de la transaction                             |
| `order_id` | `string`   | ID de transaction CrowdChange                               |
| `event_id` | `string`   | Identifiant de déduplication `transaction_<transaction_id>` |
| `contents` | `object[]` | Charges utiles de contenu TikTok                            |

**Exemple de charge utile**

```json theme={null}
{
  "currency": "CAD",
  "value": 100,
  "order_id": "1000",
  "event_id": "transaction_1000",
  "contents": [
    {
      "content_id": "donation",
      "content_name": "Donation",
      "content_category": "donation",
      "price": 100,
      "quantity": 1
    }
  ]
}
```

***

## Suivi des paiements côté serveur

Lorsqu'un ID de Pixel TikTok et un jeton d'accès à l'API Events de TikTok sont tous deux configurés, CrowdChange envoie un événement `CompletePayment` côté serveur.

| Champ         | Description                                                  |
| ------------- | ------------------------------------------------------------ |
| `pixel_code`  | ID de Pixel TikTok                                           |
| `event`       | `CompletePayment`                                            |
| `event_id`    | `transaction_<transaction_id>`                               |
| `timestamp`   | Horodatage de l'événement                                    |
| `currency`    | Devise de la transaction                                     |
| `value`       | Total de la transaction                                      |
| `order_id`    | ID de transaction CrowdChange                                |
| `contents`    | Identifiants et quantités des articles achetés               |
| `callback`    | Valeur `ttclid` capturée, si disponible                      |
| `ttp`         | Témoin de navigateur TikTok `_ttp`, si disponible            |
| `email`       | Courriel du donateur haché en SHA-256, si disponible         |
| `external_id` | ID d'utilisateur CrowdChange haché en SHA-256, si disponible |
| `ip`          | Adresse IP de la requête                                     |
| `user_agent`  | Agent utilisateur de la requête                              |

Les échecs liés au réseau publicitaire sont journalisés et n'interrompent pas le parcours de paiement du donateur.

***

## Attribution par identifiant de clic (`ttclid`)

Lorsqu'un visiteur arrive via une publicité TikTok, TikTok peut ajouter `ttclid` à l'URL. CrowdChange capture cette valeur dans la session du navigateur et la transmet aux appels de l'API Events côté serveur sous forme de `callback`. CrowdChange transmet également le témoin `_ttp` lorsqu'il est disponible.

***

## Vérifier votre configuration

Après avoir enregistré votre ID de Pixel :

1. Visitez n'importe quelle page de votre plateforme et confirmez que le Pixel TikTok se charge depuis `https://analytics.tiktok.com/i18n/pixel/events.js`
2. Naviguez entre les pages et confirmez que les événements de page se déclenchent
3. Ajoutez un article au panier et confirmez que `AddToCart` se déclenche
4. Complétez une transaction de test et confirmez que `CompletePayment` se déclenche avec la valeur, la devise et l'`event_id` attendus

Si vous avez configuré l'API Events, vérifiez l'événement côté serveur dans le gestionnaire d'événements TikTok.

***

## Renseignements supplémentaires

Consultez la [documentation du Pixel TikTok](https://ads.tiktok.com/help/article/tiktok-pixel) et la [documentation de l'API Events de TikTok](https://ads.us.tiktok.com/help/article/events-api) pour en savoir plus.