> ## 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.

# Pixel Facebook

> Installez le Pixel Facebook et l'API Conversions dans CrowdChange pour suivre les dons, recibler les visiteurs et mesurer la performance des pubs.

## Intégration du Pixel Facebook

CrowdChange prend en charge le suivi par Meta Pixel ainsi que le suivi des achats optionnel via l'API Conversions de Meta.

Une fois connecté, votre Pixel reçoit les événements de navigateur `PageView` et `Purchase` à mesure que les utilisateurs naviguent et complètent des transactions. Si un jeton d'accès à l'API Conversions de Meta est configuré, CrowdChange envoie également les achats complétés depuis le serveur et utilise un identifiant d'événement partagé pour aider Meta à dédupliquer les événements du navigateur et du serveur.

***

## Configuration

1. Accédez à **Admin -> Paramètres de mise en page -> Meta et analytique**
2. Faites défiler jusqu'à la section **Facebook Analytics**
3. Entrez votre **ID de Pixel** dans le champ *Facebook Pixel ID*, par exemple `1234567890123456`
4. Facultatif : entrez votre **jeton d'accès à l'API Conversions de Meta**
5. Facultatif : entrez votre code de **vérification de domaine** dans le champ *FB meta tag domain verification*. Utilisez uniquement la valeur de l'attribut `content` de la balise `<meta name="facebook-domain-verification" ...>` fournie par Meta
6. 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 Conversions 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

### PageView

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

| Paramètre     | Type             | Description                                                                              |
| ------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `external_id` | `string \| null` | L'identifiant de clic `fbclid` provenant de l'URL d'atterrissage du visiteur, si présent |

**Exemple de charge utile**

```json theme={null}
{
  "external_id": "fb-click-id"
}
```

***

### Purchase

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

| Paramètre      | Type       | Description                                          |
| -------------- | ---------- | ---------------------------------------------------- |
| `currency`     | `string`   | Code de devise ISO 4217, par exemple `USD`, `CAD`    |
| `value`        | `number`   | Montant total de la transaction                      |
| `content_ids`  | `string[]` | Identifiants des articles inclus dans la transaction |
| `contents`     | `object[]` | Tableau d'objets `{ id, quantity }`                  |
| `content_name` | `string`   | Titre de la page au moment de l'achat                |
| `content_type` | `string`   | Toujours `product`                                   |
| `num_items`    | `number`   | Nombre d'articles dans la transaction                |
| `external_id`  | `string`   | Le `fbclid` capturé, si présent                      |

L'événement du navigateur est envoyé avec `eventID: transaction_<transaction_id>`.

**Exemple de charge utile du navigateur**

```json theme={null}
{
  "currency": "USD",
  "value": 100,
  "content_ids": ["42", "87"],
  "contents": [
    { "id": "42", "quantity": 1 },
    { "id": "87", "quantity": 1 }
  ],
  "content_name": "Annual Gala",
  "content_type": "product",
  "num_items": 2,
  "external_id": "fb-click-id"
}
```

***

## Suivi des achats côté serveur

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

| Champ                | Description                                                                     |
| -------------------- | ------------------------------------------------------------------------------- |
| `event_id`           | `transaction_<transaction_id>` pour la déduplication navigateur/serveur         |
| `event_source_url`   | URL de la page de paiement, si disponible                                       |
| `currency`           | Devise de la transaction                                                        |
| `value`              | Total de la transaction                                                         |
| `order_id`           | ID de transaction CrowdChange                                                   |
| `content_ids`        | Identifiants des articles achetés, ou `donation` pour un flux de don uniquement |
| `contents`           | Quantités des articles achetés                                                  |
| `client_ip_address`  | Adresse IP de la requête                                                        |
| `client_user_agent`  | Agent utilisateur de la requête                                                 |
| `fbp` / `fbc`        | Témoins (cookies) de navigateur Meta, si disponibles                            |
| `em` / `external_id` | Courriel du donateur et ID d'utilisateur hachés en SHA-256, si disponibles      |

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 (`fbclid`)

Lorsqu'un visiteur arrive via une publicité Meta, Meta peut ajouter `fbclid` à l'URL. CrowdChange le capture dans la session du navigateur et l'utilise pour les événements du Pixel côté navigateur. Pour les achats côté serveur, CrowdChange transmet également les témoins `_fbp` et `_fbc` lorsqu'ils sont disponibles, et dérive `_fbc` à partir de `fbclid` lorsque le témoin est manquant.

***

## Vérification de domaine

Pour vérifier votre domaine auprès de Meta :

1. Dans Meta Business Manager, accédez à **Sécurité de la marque -> Domaines** et ajoutez votre domaine
2. Copiez le code de vérification depuis la balise `<meta name="facebook-domain-verification" content="...">`
3. Collez uniquement la valeur `content` dans le champ **FB meta tag domain verification**
4. Cliquez sur **Enregistrer**
5. Retournez sur Meta et cliquez sur **Vérifier**

***

## Vérifier votre configuration

Après avoir enregistré votre ID de Pixel :

1. Installez l'extension Chrome [Meta Pixel Helper](https://chromewebstore.google.com/detail/meta-pixel-helper/fdgfkebogiimcoedlicjlajpkdmockpc)
2. Visitez n'importe quelle page de votre plateforme
3. Confirmez que l'extension montre que votre ID de Pixel déclenche `PageView`
4. Complétez une transaction de test et confirmez que `Purchase` se déclenche avec la valeur et la devise attendues

Si vous avez configuré l'API Conversions, vérifiez également dans **Meta Events Manager -> Test Events** et confirmez que la déduplication navigateur/serveur utilise le même identifiant d'événement `transaction_<transaction_id>`.

***

## Renseignements supplémentaires

Consultez la [documentation du Meta Pixel](https://developers.facebook.com/docs/meta-pixel) et la [documentation de l'API Conversions de Meta](https://developers.facebook.com/docs/marketing-api/conversions-api/get-started) pour en savoir plus.