API Offline Conversions

Utilisez l’API Offline Conversions pour envoyer des évènements de conversion hors ligne et découvrez combien de client·es ont vu vos publicités Facebook ou cliqué dessus avant d’effectuer une conversion.

Avant de commencer

Pour utiliser cette API, vous avez besoin des éléments suivants :

1. Meta Business Manager

Si vous n’en avez pas, créez-en un.

2. ID d’application Meta

Pour accéder à l’API Marketing. Pour créer une application Meta :

• Accédez à Business Manager > Paramètres d’entreprise.
• Sélectionnez Apps.
• Cliquez sur Ajouter une nouvelle app et suivez les instructions.

3. Contrôle app et autorisations

Les règles pour Contrôle app et les autorisations dépendent de la manière dont vous implémentez notre API :

4. Token et utilisateur système Business Manager

Grâce à l’accès utilisateur système, votre application peut envoyer des données à Meta par l’intermédiaire de l’API. Pour le créer :

• Accédez à Business Manager > Paramètres d’entreprise.
• Sélectionnez Utilisateurs système.
• Cliquez sur Ajouter un nouvel utilisateur système.
• Sélectionnez Utilisateur système admin comme rôle de l’utilisateur système.

Un token d’accès donne accès aux données Meta. Pour créer les tokens d’accès de l’utilisateur système :

• Accédez à Business Manager > Paramètres d’entreprise.
• Sélectionnez Utilisateurs système.
• Sélectionnez l’utilisateur système et cliquez sur Générer un nouveau token.
• Sélectionnez votre application et pour la portée, sélectionnez ads_management.

5. Compte publicitaire

Vous devez posséder un compte publicitaire pour diffuser des campagnes publicitaires sur Meta. Pour en créer un, consultez la section API Marketing ou les Pages d’aide Business, à propos des paramètres de l’entreprise dans Meta Business Manager.

6. Accorder un accès Utilisateur système à un compte publicitaire

Accordez un accès Utilisateur système à votre compte publicitaire.

• Accédez à Business Manager > Paramètres d’entreprise.
• Sélectionnez Utilisateurs système.
• Sélectionnez l’utilisateur système et cliquez sur Attribuer des ressources.
• Sélectionnez votre compte publicitaire.

7. Ensemble d’évènements hors ligne

Il s’agit de fichiers importés avec des données de conversion hors ligne. Lorsque vous créez une publicité, définissez tracking_spec sur l’ID de l’ensemble d’évènements hors ligne pour attribuer correctement des évènements. Vous pouvez ensuite créer des ensembles d’évènements, consulter des statistiques sur vos importations, puis supprimer et modifier ces données dans Business Manager.

Dans les anciennes implémentations, vous pouviez effectuer des opérations CRUD sur un ensemble d’évènements hors ligne au niveau de Business Manager afin de partager des ensembles d’évènements avec d’autres objets et entités.

Importer des données d’évènement

Vous avez besoin d’un accès particulier pour créer des ensembles d’évènements hors ligne et importer ou consulter des données relatives à un ensemble d’évènements. Vous avez également besoin de cet accès pour attribuer ces autorisations à un compte publicitaire. Vous devez avoir l’un des rôles suivants :

• Admin Business Manager
• Utilisateur système admin ayant créé l’ensemble d’évènements hors ligne
• Admin sur le ad_account connecté à l’ensemble d’évènements hors ligne

Consultez la documentation de référence sur l’ensemble d’évènements de conversion hors ligne.

1. Créer un ensemble d’évènements hors ligne

curl 
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' 
  -F 'name=offline_event_set',
  -F 'description=conversion data used for superbowl campaign',
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

Envoyez une requête HTTP POST :

POST /<BUSINESS_MANAGER_ID>/offline_conversion_data_sets HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<BUSINESS_MANAGER_ID>/offline_conversion_data_sets

La réponse contient un id d’ensemble d’évènements :

{
  "id": <OFFLINE_EVENT_SET_ID>
}

Paramètres

2. Attribuer des autorisations à un compte publicitaire

Pour attribuer des autorisations de suivi et de lecture à un compte publicitaire :

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Paramètres

3. Définir le suivi publicitaire

Lorsque vous mettez à jour tracking_spec, nous l’écrasons. Assurez-vous d’effectuer GET d’abord, puis ajoutez le paramètre String de l’ensemble d’évènements hors ligne au paramètre tracking_spec existant. Consultez la section Gestion des publicités ou utilisez le Gestionnaire de publicités. Par exemple, indiquez une spécification de suivi appropriée :

curl \
  -F 'tracking_spec=[{action.type:"offline_conversion", dataset:["123"]}]' \
  -F 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<AD_ID>

Pour mettre à jour la spécification de suivi de vos publicités :

POST /<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}] HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<AD_ID>/?tracking_specs=[{"action.type":"offline_conversion","dataset": <OFFLINE_EVENT_SET_ID>}]

Paramètres

4. Importer des évènements hors ligne

Vous devez importer la transaction dans les 62 jours suivant la conversion. Importez les données de conversion :

curl \
  -F 'access_token=SYSTEM_USER_ACCESS_TOKEN' \
  -F 'upload_tag=store_data' \
  -F 'data=[ \
    { 
      match_keys: {"phone": ["HASH1","HASH2"], "email": ["HASH3","HASH4"]}, 
      currency: "USD", 
      value: 16,
      event_name: "Purchase",
      event_time: 1456870902,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {             
      },
    }, 
    { 
      match_keys: {"lead_id": "12345"}, 
      event_name: "Lead",
      event_time: 1446336000,
      contents: [
        {id: "A", quantity: 1},
        {id: "B", quantity: 2},
        {id: "C", quantity: 1}
      ]
      custom_data: {
        event_source: "email",
        action_type: "sent_open_click",
        email_type: "email_type_code", 
        email_provider: "gmail_yahoo_hotmail",
      }
    }, 
  ]'
  https://graph.facebook.com/VERSION/OFFLINE_EVENT_SET_ID/events

Pour envoyer des conversions, effectuez une requête HTTP POST :

POST /<OFFLINE_EVENT_SET_ID>/events HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/events

Paramètres

Utilisez le même paramètre upload_tag pour tous les appels d’API d’importation d’évènements appartenant au même lot afin de les regrouper. Cela vous aide à débuguer les importations d’évènements. Vous devez utiliser ce paramètre pour toutes les importations d’évènements effectuées dans plusieurs appels d’API.

Les paramètres inclus dans data sont les suivants :

Par exemple, vous pouvez importer des informations à l’aide du champ data :

{
  match_keys: MATCH_KEYS,
  event_time: EVENT_TIME,
  event_name: "Purchase",
  value: 400,
  currency: "USD",
  contents: [
    {
        id: "A",
        quantity: 1,
        brand: "brand_of_A",
        category: "Apparel & Accessories | Clothing",
        price: 100,
    },
    {
        id: "B",
        quantity: 2,
        brand: "brand_of_B",
        category: "Apparel & Accessories | Shoes",
        price: 50,
    },
    {
        id: "C",
        quantity: 1,
        brand: "brand_of_C",
        category: "Apparel & Accessories | Jewelry | Watches",
        price: 200,
    }
  ],
}

Utilisez le même paramètre upload_tag pour tous les appels d’API d’importation d’évènements appartenant au même lot afin de les regrouper. Cela vous permet de déboguer des importations d’évènements. Vous devez utiliser ce paramètre pour toutes les importations d’évènements effectuées dans plusieurs appels d’API.

Clés de correspondance

match_keys est un ensemble d’identifiants utilisés pour faire correspondre des personnes en vue de l’attribution. Consultez la section Audiences personnalisées issues de données CRM pour savoir comment normaliser et hacher vos données. Seule la méthode SHA256 est prise en charge et nous n’acceptons pas les données non hachées.

Réponse :

Les erreurs affichent une exception contenant des entrées non valides, ainsi que le motif. Corrigez les erreurs ou ignorez les lignes de données contenant des erreurs et réessayez l’appel d’API.

Afficher des statistiques d’importation

Un ou une admin de Business Manager ou un utilisateur système ayant créé l’ensemble d’évènements hors ligne peut récupérer des statistiques d’importation. En outre, les admins du ad_account connecté à l’ensemble d’évènements hors ligne peuvent toutes et tous lire ces données.

Pour consulter des statistiques sur des ensembles d’évènements hors ligne, comme des entrées valides et mises en correspondance :

GET /<OFFLINE_EVENT_SET_ID>/uploads HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/uploads

Consultez les répartitions quotidiennes des évènements hors ligne du Offline Events Manager dans Business Manager. Pour consulter des répartitions plus précises, effectuez cet appel :

GET /<OFFLINE_EVENT_SET_ID>/stats HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/stats

Paramètres

Créer des conversions personnalisées hors ligne

Actuellement, les conversions personnalisées hors ligne ne sont pas ajoutées. Nous n’attribuons pas les données issues des importations d’évènements effectuées avant la création de la conversion personnalisée. Vous ne pouvez pas utiliser les données d’une conversion personnalisée hors ligne pour optimiser la diffusion des publicités. Consultez la section Conversion personnalisée : documentation de référence.

Pour créer une conversion personnalisée à l’aide de vos évènements hors ligne, effectuez une POST :

POST /act_<ACCOUNT_ID>/customconversions HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ACCOUNT_ID>/customconversions

Paramètres :

Réponse si l’opération a abouti :

{
  "id": <CUSTOM_CONVERSION_ID>
}

Mesurer avec des données personnalisées

Utilisez le champ custom_data pour créer des règles qui déterminent plus tard si une conversion compte ou non. Cela est semblable aux Audiences personnalisées hors ligne. Le nombre maximal de conversions personnalisées que vous pouvez avoir par compte publicitaire est de 40.

Par exemple, incluez une catégorie de produit dans des importations avec custom_data :

data=[
  {
    match_keys: {"phone": ["<HASH>","<HASH>"], "email": ["<HASH>","<HASH>"]}, 
    currency: "USD", 
    value: 16,
    event_name: "Purchase",
    event_time: 1456870902,
    custom_data: {
      product_category: "ICECREAM",
    },
  },
]

Utilisez ensuite custom_data.{YOUR_CUSTOM_PARAM} pour créer une règle relative à la conversion personnalisée :

curl \
  -F 'name=Ice Cream Purchasers' \
  -F 'custom_event_type=Purchase' \
  -F 'event_source_id=<OFFLINE_EVENT_SET_ID>' \
  -F 'rule={"and": [{"event_name":{"eq":"Purchase"}},{"custom_data.product_category":{"i_contains":"ICECREAM"}}]}' \
  -F 'access_token=<ACCESS_TOKEN>' \

"https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/customconversions"

Conversions hors ligne pour les partenaires

Pour attribuer des évènements de conversion hors ligne à la publicité de votre client ou cliente, suivez les étapes suivantes. Pour la plupart de ces étapes, les appels d’API sont les mêmes que lorsqu’une personne gère son propre ensemble d’évènements hors ligne et sa propre campagne.

1. Partenaire : créer un ensemble d’évènements hors ligne
2. Partenaire : partager un ensemble d’évènements avec le compte Business Manager du client ou de la cliente
3. Client·e : attribuer une autorisation de suivi hors ligne au compte publicitaire
4. Client·e : définir un suivi hors ligne sur les publicités
5. Partenaire : importer des évènements hors ligne, consulter des statistiques
6. Partenaire : afficher des insights publicitaires pour le client ou la cliente

Ces étapes varient selon la façon dont les autorisations de votre partenaire ou agence sont configurées avec les comptes publicitaires du client ou de la cliente :

• Tous les comptes publicitaires, ensembles d’évènements ou toutes les autres ressources de votre client ou cliente peuvent vous appartenir.
• Vous pouvez être autorisé·e à utiliser les ressources de votre client ou cliente pour effectuer certaines actions.

Pour configurer ces autorisations, consultez la section Ressources de Business Manager.

Partenaire : partager un ensemble d’évènements

Partagez l’ensemble d’évènements avec le compte Business Manager de votre client ou cliente. Votre client ou votre cliente peut ensuite utiliser l’ensemble d’évènements pour le suivi des publicités.

GET /<OFFLINE_EVENT_SET_ID>/agencies HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/agencies

Paramètres

Client·e : attribuer une autorisation de suivi hors ligne au compte publicitaire

Partagez des ensembles d’évènements hors ligne créés par un partenaire avec son client ou sa cliente. Pour activer le suivi des publicités dans un compte publicitaire, vous devez être admin de Business Manager ou utilisateur système admin ayant créé l’ensemble d’évènements hors ligne. Vous pouvez également effectuer cette opération si vous êtes admin du compte publicitaire associé à l’ensemble d’évènements hors ligne. Pour effectuer cet appel d’API, l’entreprise passant l’appel doit avoir accès à l’ensemble d’évènements hors ligne.

Vous pouvez attribuer des autorisations de suivi et de consultation d’évènement hors ligne à un compte publicitaire avec cet appel :

POST /<OFFLINE_EVENT_SET_ID>/adaccounts HTTP/1.1
Host: graph.facebook.com

curl -X POST \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<OFFLINE_EVENT_SET_ID>/adaccounts

Paramètres

Fourniture d’ID externes

Dans certains cas, vous pouvez être amené·e à fournir votre propre ID externe pour représenter un client ou une cliente et le ou la faire correspondre à un utilisateur ou une utilisatrice. Pour cela, utilisez l’extern_id conformément aux règles ci-après.

Les partenaires de données qui ont exécuté le processus de mise en correspondance peuvent utiliser l’ID de partenaire comme ID d’espace de nom et l’extern_id comme tpid.

Fournir uniquement match_keys

Nous utilisons match_keys pour tenter de déterminer si les données de conversion que vous avez partagées peuvent être associées à un utilisateur ou une utilisatrice de Meta. Si vous fournissez match_keys, vous ne pouvez pas fournir dans le même temps un paramètre namespace_id.

Fournir à la fois match_keys et extern_id

Nous utilisons match_keys pour tenter de trouver des personnes sur Meta et transférer des mappages de {dataset_id, extern_id} à {facebook_user_id}. Si vous fournissez match_keys et extern_id, vous ne pouvez pas dans le même temps indiquer namespace_id.

Fournir uniquement extern_id

Si vous avez déjà envoyé des données avec match_keys et extern_id, Meta utilise {dataset_id, extern_id} pour récupérer un {facebook_user_id}.

Fournir namespace_id

Le paramètre namespace_id s’applique à l’intégralité de l’appel d’API. Vous pouvez l’utiliser pour faire référence à un autre ensemble d’évènements hors ligne accessibles ou appartenant à un ID d’entreprise ou de profil de partenaire. Si vous avez déjà envoyé des données avec match_keys et extern_id, Meta utilise {namespace_id, extern_id} pour récupérer un {facebook_user_id}. Vous ne devez fournir qu’un seul paramètre extern_id par ligne de données.

Insights et attribution

Consultez les évènements hors ligne attribués à une publicité qu’une personne a vue ou sur laquelle elle a cliqué. Nous attribuons des conversions hors ligne après plus d’un jour. Cela signifie que vous devez définir votre fenêtre d’attribution sur 28d_view ou action_attribution_windows=['28d_view']' pour afficher toutes les conversions dans des rapports. Consultez les sections API Insights et Guide des statistiques.

GET /act_<ADACCOUNT_ID>/insights HTTP/1.1
Host: graph.facebook.com

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/act_<ADACCOUNT_ID>/insights

Paramètres

Les résultats se présentent comme suit :

{
  "data": [
    {
      "date_start": "2015-12-01",
      "date_stop": "2015-12-01",
      "actions": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
          "action_type": "offsite_conversion.lead",
          "value": 3
        },
      ],
      ...
    }
  ]
}

Par exemple, pour consulter l’attribution :

curl -G \
  -d 'access_token=<SYSTEM_USER_ACCESS_TOKEN>' \
  -d 'fields=unique_actions,action_values' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

Le résultat se présente comme suit :

{
  "data": [
    {
      "unique_actions": [
        {
          "action_type": "link_click",
          "value": 94
        },
        {
          "action_type": "offline_conversion",
          "value": 1
        },
        {
          "action_type": "offline_conversion.purchase",
          "value": 1
        },
        {
....
          "value": 1
        }
      ],
      "action_values": [
        {
          "action_type": "offline_conversion.purchase",
          "value": 27.5
        },
        {
          "action_type": "offline_conversion",
          "value": 27.5
        }
      ],
      "date_start": "2016-06-06",
      "date_stop": "2016-06-07"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Options de traitement des données pour les utilisateur·ices des États-Unis

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}

En savoir plus sur les options de traitement des données.