> For the complete documentation index, see [llms.txt](https://cmp.docs.sirdata.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cmp.docs.sirdata.net/faq/facebook/meta-retargeting-and-conversions-api-capi.md).

# Meta Retargeting & Conversions API (CAPI)

> Ce document couvre le fonctionnement du retargeting Meta, du Pixel client-side à la Conversions API server-side, avec une attention particulière sur le matching utilisateur et les bonnes pratiques d'implémentation.

***

### Vue d'ensemble

Le retargeting Meta repose sur la capacité de Meta à **faire le lien entre un visiteur de site web et un utilisateur Facebook/Instagram**. Pour ça, Meta utilise deux canaux complémentaires :

| Canal               | Déclenchement   | Résistance ITP/adblock | Richesse données |
| ------------------- | --------------- | ---------------------- | ---------------- |
| **Pixel Meta**      | Navigateur (JS) | Faible                 | Moyenne          |
| **Conversions API** | Serveur (HTTP)  | Totale                 | Élevée           |

L'approche recommandée est le **mode hybride** : Pixel + CAPI en parallèle, avec déduplication.

***

### Comment Meta identifie un utilisateur

C'est la question centrale. Meta ne connaît pas l'identité réelle du visiteur — il cherche à **matcher** des signaux techniques avec son annuaire d'utilisateurs connectés.

#### Les identifiants utilisés

**1. Cookies Meta (`_fbp` et `_fbc`)**

* **`_fbp`** (Facebook Browser ID) : posé par le Pixel sur le domaine du site, identifie le navigateur de manière unique. Durée de vie : 90 jours.
* **`_fbc`** (Facebook Click ID) : posé quand l'utilisateur arrive sur le site via un clic sur une pub Meta (paramètre `fbclid` dans l'URL).

Ces cookies sont lisibles **uniquement par le site lui-même** (first-party), mais leur valeur est transmise à Meta via le Pixel ou la CAPI.

**2. Données personnelles hashées (PII)**

Via la CAPI, il est possible d'envoyer des données utilisateur **hashées en SHA-256** :

```
email brut → SHA-256 → a665a45920422f9d...
```

Meta compare ce hash avec les hashs de sa propre base. Si ça correspond → match.

Les données supportées :

* Email (`em`)
* Téléphone (`ph`)
* Prénom (`fn`), Nom (`ln`)
* Date de naissance (`db`)
* Genre (`ge`)
* Ville (`ct`), Code postal (`zp`), Pays (`country`)

> **Important** : le hash SHA-256 est irréversible. Meta ne récupère jamais l'email en clair. C'est le principe du *privacy-preserving matching*.

**3. Signaux contextuels**

* Adresse IP (`client_ip_address`)
* User Agent (`client_user_agent`)
* URL de la page (`event_source_url`)

Ces signaux seuls sont insuffisants pour un match fiable, mais ils renforcent la confiance du matching quand combinés aux autres.

#### Le score de matching

Meta attribue un **Event Match Quality (EMQ)** entre 0 et 10 à chaque événement reçu. Plus le score est élevé, plus Meta est confiant dans l'identification de l'utilisateur, et plus le retargeting sera efficace.

```
EMQ faible (< 6)  → peu de signaux → audience incomplète
EMQ élevé (> 7)   → signaux riches → matching précis
```

Pour maximiser l'EMQ : envoyer `_fbp` + `_fbc` + email hashé + IP + user agent.

***

### Le Pixel Meta (client-side)

#### Fonctionnement

Le Pixel est un snippet JavaScript chargé dans le navigateur. Il :

1. Lit les cookies `_fbp` / `_fbc` existants (ou les crée)
2. Collecte l'IP, user agent, URL
3. Envoie une requête HTTP vers `https://www.facebook.com/tr/`

#### Événements standards

| Événement          | Déclenchement typique    |
| ------------------ | ------------------------ |
| `PageView`         | Toutes les pages         |
| `ViewContent`      | Page produit / article   |
| `AddToCart`        | Ajout au panier          |
| `InitiateCheckout` | Début de checkout        |
| `Purchase`         | Confirmation de commande |
| `Lead`             | Soumission de formulaire |

#### Exemple de code

```html
<!-- Pixel de base -->
<script>
!function(f,b,e,v,n,t,s){...}(window, document,'script',
'https://connect.facebook.net/en_US/fbevents.js');
fbq('init', 'PIXEL_ID');
fbq('track', 'PageView');
</script>

<!-- Événement Purchase avec données -->
<script>
fbq('track', 'Purchase', {
  value: 49.99,
  currency: 'EUR',
  content_ids: ['SKU-123'],
  content_type: 'product'
});
</script>
```

#### Limites du Pixel seul

* **Bloqueurs de publicités** : Firefox + uBlock Origin bloque `connect.facebook.net`
* **ITP (Safari)** : les cookies third-party sont limités à 7 jours, voire 24h
* **Perte de signal estimée** : 20 à 40% des événements selon les configurations

C'est pour pallier ces limites que la CAPI existe.

***

### La Conversions API (server-side)

#### Principe

La CAPI permet d'envoyer les événements **directement depuis le serveur** vers l'API Meta, sans passer par le navigateur. Les bloqueurs et les restrictions de cookies n'ont aucun impact.

```
Navigateur
    │
    │  requête HTTP
    ▼
Ton serveur (ou GTM SS)
    │
    │  POST /v19.0/{pixel_id}/events
    ▼
API Meta
```

#### Endpoint

```
POST https://graph.facebook.com/v19.0/{PIXEL_ID}/events
     ?access_token={ACCESS_TOKEN}
```

#### Structure d'un payload CAPI

```json
{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1714000000,
      "event_id": "evt_order_9876",
      "event_source_url": "https://monsite.com/merci",
      "action_source": "website",
      "user_data": {
        "em": ["a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"],
        "ph": ["b3b3b3b3..."],
        "client_ip_address": "82.65.12.34",
        "client_user_agent": "Mozilla/5.0 (Macintosh...)",
        "fbp": "fb.1.1714000000000.1234567890",
        "fbc": "fb.1.1714000000000.IwAR1..."
      },
      "custom_data": {
        "value": 49.99,
        "currency": "EUR",
        "content_ids": ["SKU-123"],
        "content_type": "product",
        "order_id": "ORD-9876"
      }
    }
  ]
}
```

#### Points clés

* **`event_id`** : identifiant unique de l'événement — **indispensable pour la déduplication** avec le Pixel
* **`event_time`** : timestamp Unix en secondes
* **`action_source`** : toujours `"website"` pour les événements web
* **`em` et `ph`** : tableaux — Meta accepte plusieurs hashs (ex. email normalisé + email avec majuscule)

#### Normalisation avant hash

Meta impose des règles de normalisation **avant** de hasher :

| Champ        | Normalisation                                                |
| ------------ | ------------------------------------------------------------ |
| Email        | lowercase, trim des espaces                                  |
| Téléphone    | chiffres uniquement, avec indicatif pays (ex. `33612345678`) |
| Prénom / Nom | lowercase, trim, sans accents                                |
| Code postal  | trim                                                         |

```javascript
// Exemple de normalisation email
const hashEmail = (email) => {
  const normalized = email.toLowerCase().trim();
  return crypto.createHash('sha256').update(normalized).digest('hex');
};
```

***

### Déduplication Pixel + CAPI

Quand Pixel et CAPI sont actifs simultanément, Meta peut recevoir **deux fois le même événement**. La déduplication évite de comptabiliser deux conversions.

#### Mécanisme

Meta déduplique sur deux critères combinés :

* **`event_name`** identique
* **`event_id`** identique

Si ces deux valeurs sont les mêmes entre l'événement Pixel et l'événement CAPI reçus dans une fenêtre de \~48h, Meta ne compte qu'**une seule conversion**.

#### Implémentation

**Côté Pixel (dataLayer / GTM) :**

```javascript
dataLayer.push({
  event: 'purchase',
  meta_event_id: 'evt_order_9876', // ID unique généré côté serveur
  transaction_id: 'ORD-9876',
  value: 49.99,
  currency: 'EUR'
});
```

**Dans le tag Pixel (GTM) :**

```javascript
fbq('track', 'Purchase', {
  value: {{DL - value}},
  currency: {{DL - currency}}
}, {
  eventID: {{DL - meta_event_id}} // ← même ID que la CAPI
});
```

**Côté CAPI :**

```json
{
  "event_name": "Purchase",
  "event_id": "evt_order_9876"  // ← même ID
}
```

> **Bonne pratique** : générer l'`event_id` côté backend au moment de l'événement, le passer dans le dataLayer pour le Pixel, et l'utiliser directement dans la requête CAPI.

***

### Implémentation via GTM Server-Side

GTM Server-Side est la solution la plus propre pour implémenter la CAPI sans développement backend custom.

#### Architecture

```
Navigateur
    │
    │  hits vers ton domaine (collect.monsite.com)
    ▼
GTM Server-Side Container
    │
    ├──► Tag Meta CAPI → API Meta
    ├──► Tag GA4 SS → Google Analytics
    └──► Tag autres...
```

#### Setup

**1. Client GTM SS**

Utiliser le **client GA4** natif ou un client custom selon la source des données. Il reçoit les hits du navigateur et les transforme en événements exploitables par les tags.

**2. Tag Meta CAPI**

Utiliser le template officiel **"Facebook Conversions API"** disponible dans la galerie de templates GTM.

Configuration minimale :

* **Pixel ID** : ton ID pixel Meta
* **Access Token** : généré dans Meta Business Manager → Paramètres du pixel → CAPI
* **Event Name** : mappé depuis l'événement entrant
* **Event ID** : récupéré depuis le dataLayer (pour déduplication)

**3. Récupération des données utilisateur**

Le tag CAPI doit pouvoir accéder aux données de matching. Deux approches :

**Option A — via le dataLayer enrichi (côté client)**

Le site pousse les données dans le dataLayer :

```javascript
dataLayer.push({
  event: 'purchase',
  user: {
    email: 'user@example.com', // sera hashé par GTM SS
    phone: '+33612345678'
  },
  fbp: getCookie('_fbp'),
  fbc: getCookie('_fbc')
});
```

**Option B — enrichissement côté serveur**

Le container SS récupère les cookies `_fbp` / `_fbc` depuis les headers de la requête entrante, et les données utilisateur depuis une API interne ou un cookie first-party chiffré.

**4. Variables GTM SS utiles**

```
{{Request Header - x-forwarded-for}}  → IP réelle du visiteur
{{Request Header - user-agent}}        → User Agent
{{Cookie - _fbp}}                      → Facebook Browser ID
{{Cookie - _fbc}}                      → Facebook Click ID
```

**5. Exemple de mapping dans le tag CAPI**

| Champ CAPI          | Variable GTM SS                                          |
| ------------------- | -------------------------------------------------------- |
| `client_ip_address` | `{{Request Header - x-forwarded-for}}`                   |
| `client_user_agent` | `{{Request Header - user-agent}}`                        |
| `fbp`               | `{{Cookie - _fbp}}`                                      |
| `fbc`               | `{{Cookie - _fbc}}`                                      |
| `em`                | `{{DL - user.email}}` (hashé automatiquement par le tag) |
| `event_id`          | `{{DL - meta_event_id}}`                                 |

***

### Gestion du consentement (CMP)

#### Principe

Le RGPD impose de ne collecter des données à des fins publicitaires qu'après **consentement explicite** de l'utilisateur. Cela s'applique au Pixel Meta **et** à la CAPI.

#### Implémentation avec une CMP (ex. Sirdata)

**Côté Pixel (GTM client-side)**

Le tag Pixel doit avoir un **trigger conditionné au consentement** :

```
Trigger : Consent Initialization
Condition : Analytics Storage = granted
         ET Ad Storage = granted
```

Ou via le Consent Mode de Google : activer le tag uniquement si `ad_storage` et `analytics_storage` sont en `granted`.

**Côté CAPI (GTM server-side)**

La CAPI est déclenchée côté serveur, mais elle doit **refléter le consentement côté client**. Deux approches :

**La balise Sirdata permet de le faire nativement**

***

### Paramètres de matching — référence complète

| Paramètre           | Clé CAPI            | Hash requis | Priorité EMQ |
| ------------------- | ------------------- | ----------- | ------------ |
| Email               | `em`                | SHA-256     | ⭐⭐⭐⭐⭐        |
| Téléphone           | `ph`                | SHA-256     | ⭐⭐⭐⭐         |
| Facebook Browser ID | `fbp`               | Non         | ⭐⭐⭐⭐         |
| Facebook Click ID   | `fbc`               | Non         | ⭐⭐⭐⭐         |
| IP                  | `client_ip_address` | Non         | ⭐⭐⭐          |
| User Agent          | `client_user_agent` | Non         | ⭐⭐⭐          |
| Prénom              | `fn`                | SHA-256     | ⭐⭐           |
| Nom                 | `ln`                | SHA-256     | ⭐⭐           |
| Date de naissance   | `db`                | SHA-256     | ⭐⭐           |
| Genre               | `ge`                | SHA-256     | ⭐            |
| Ville               | `ct`                | SHA-256     | ⭐            |
| Code postal         | `zp`                | SHA-256     | ⭐            |
| Pays                | `country`           | SHA-256     | ⭐            |


---

# 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://cmp.docs.sirdata.net/faq/facebook/meta-retargeting-and-conversions-api-capi.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.