API Insights

Cette API présente une interface simple et cohérente permettant de récupérer les statistiques d’une publicité.

• Répartitions : regroupement des résultats.
• Répartitions des actions : guide des réponses des répartitions des actions.
• Tâches asynchrones : pour les demandes présentant de nombreux résultats, utilisez des tâches asynchrones.
• Limites et recommandations : limites d’appel, filtrage et recommandations.

Avant de pouvoir obtenir des données sur les performances de vos publicités, vous devez configurer vos publicités afin de suivre les indicateurs qui vous intéressent. Pour ce faire, vous pouvez utiliser les tags d’URL, le pixel Meta et l’API Conversions.

Avant de commencer

Vous aurez besoin des éléments suivants :

• L’autorisation ads_read
• Une application Consultez la page Développement d’applications Meta pour plus d’informations.

Statistiques de campagne

Pour obtenir les statistiques concernant les performances d’une campagne sur les sept derniers jours :

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

Pour en savoir plus, consultez la rubrique Ad Insights, référence.

Passer des appels

L’API Insights est disponible en tant qu’arête sur n’importe quel objet publicitaire.

Requête

Vous pouvez envoyer une requête contenant des champs spécifiques en utilisant une liste séparée par des virgules dans les paramètres fields. Par exemple :

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_OBJECT_ID/insights"
    

Réponse

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Niveaux

Résultats agrégés au niveau d’un objet défini. Cela permet de dédupliquer automatiquement les données.

Requête

Par exemple, obtenez les insights d’une campagne au niveau de la publicité.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/CAMPAIGN_ID/insights"

Réponse

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Si vous ne pouvez pas accéder à tous les objets publicitaires au niveau demandé, l’appel d’insights ne renvoie pas de données. Par exemple, lorsque vous envoyez une requête d’insights avec le paramètre level défini sur ad, si vous n’avez pas accès à l’un des objets publicitaires du compte publicitaire, cet appel d’API renvoie une erreur d’autorisation.

Fenêtres d’attribution

La fenêtre d’attribution des conversions présente des périodes qui définissent à quel moment nous attribuons un évènement à une publicité dans une application Meta. Pour obtenir des informations générales, consultez les Pages d’aide Meta Business : À propos des fenêtres d’attribution. Nous mesurons les actions qui se produisent lors d’un évènement de conversion et revenons en arrière sur 1 jour et 7 jours. Pour afficher les actions attribuées à différentes fenêtres d’attribution, envoyez une requête à /{ad-account-id}/insights. Si vous ne renseignez pas action_attribution_windows, nous utilisons 7d_click et nous l’indiquons sous value.

Par exemple, si vous indiquez action_attribution_windows, la valeur Value est associée à la fenêtre d’attribution 7d_click. Envoyez une requête à act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view']. Vous obtenez alors ce résultat :

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

Élargissement de champ

Effectuez une requête de champs au niveau du nœud et par champ indiqué dans l’élargissement de champ.

Requête

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_ID"

Réponse

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Tri

Triez les résultats en renseignant le paramètre sort avec {fieldname}_descending ou {fieldname}_ascending :

Requête

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_SET_ID/insights"

Réponse

{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

Étiquettes de publicités

Statistiques pour toutes les étiquettes dont le nom est identique. Regroupées sous une seule valeur au niveau d’un objet publicitaire. Pour en savoir plus, consultez Étiquettes de publicités, référence.

Requête

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_OBJECT_ID/insights"

Réponse

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

Définition des clics

Afin de mieux comprendre les indicateurs concernant les clics que Meta propose aujourd’hui, lisez les définitions et l’utilisation de chacun d’entre eux ci-dessous :

• Clics sur un lien, actions:link_click : nombre de clics sur des liens publicitaires vers certaines destinations ou expériences, sur des propriétés de Meta ou de tiers. Consultez les Pages d’aide publicitaire relatives aux clics sur un lien.

• Clics (tous), clicks : cet indicateur comptabilise plusieurs types de clics sur votre publicité, notamment certains types d’interactions avec le conteneur publicitaire, les liens vers d’autres destinations et les liens vers des expériences publicitaires étendues. Consultez la rubrique Clics (tous) des pages d’aide sur les publicités.

Objets supprimés et archivés

Les unités publicitaires peuvent être DELETED ou ARCHIVED. Les statistiques des objets supprimés ou archivés apparaissent lorsque vous interrogez les parents. Cela signifie que si vous interrogez les impressions au niveau de l’ensemble de publicités, les résultats comprennent les impressions de toutes les publicités de l’ensemble, même les publicités supprimées ou archivées. Consultez également les recommandations concernant le stockage et la récupération des objets publicitaires.

Toutefois, si vous effectuez une requête en utilisant le paramètre filtering, un filtrage des statuts sera appliqué par défaut pour renvoyer uniquement les objets actifs. En conséquence, les statistiques totales du nœud parent peuvent être plus importantes que les statistiques de ses enfants.

Vous pouvez cependant obtenir les statistiques des objets ARCHIVED à partir de leur nœud parent en renseignant un paramètre filtering supplémentaire.

Requête

Pour obtenir les statistiques de toutes les publicités ARCHIVED d’un compte publicitaire, répertoriées une à une :

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/insights/"

Réponse

Veuillez noter que seuls les objets archivés sont renvoyés dans cette réponse.

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

Insights concernant les objets supprimés

Vous pouvez interroger les insights d’objets supprimés si vous disposez de leur identifiant ou à l’aide du filtre ad.effective_status.

Requête

Par exemple, si vous avez l’ID d’ensemble de publicités :

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v21.0/AD_SET_ID"
    

Dans cet exemple de requête, nous utilisons ad.effective_status :

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

Réponse

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

Dépannage

Délais d’expiration

Les requêtes en trop grand nombre et les délais d’expiration constituent les problèmes les plus courants entraînant un échec au niveau de ce point de terminaison.

• Avec les requêtes /GET ou synchrones, vous risquez d’obtenir des erreurs de mémoire insuffisante ou de délai d’expiration.
• Avec les requêtes /POST ou asynchrones, il est possible que vous obteniez des erreurs de délai d’expiration. Pour les demandes asynchrones, la finalisation d’une requête comprenant des tentatives peut prendre jusqu’à une heure. Par exemple, si vous envoyez une requête pour tenter de récupérer un volume important de données concernant un grand nombre d’objets au niveau de la publicité.

Recommandations

• Il n’existe pas de limite explicite indiquant à quel moment une requête échouera. En cas de délai d’expiration, essayez de scinder la requête en plusieurs requêtes moins importantes en appliquant des filtres tels qu’une plage de date.
• Le calcul d’indicateurs uniques prend du temps. Essayez d’interroger les indicateurs uniques dans un appel distinct afin d’améliorer les performances des indicateurs non uniques.

Plafond

L’API Meta Insights applique un plafond afin de garantir une génération de rapports optimale à l’ensemble de nos partenaires. Pour plus d’informations et de suggestions, consultez les Limites et recommandations concernant l’API Insights.

Différence avec le gestionnaire de publicités

Le comportement par défaut de l’API est différent du comportement par défaut dans le gestionnaire de publicités. Si vous souhaitez que l’API se comporte comme le gestionnaire de publicités, définissez le champ use_account_attribution_setting sur « true ».

En savoir plus

• Insights des comptes publicitaires
• Insights des campagnes publicitaires
• Insights des ensembles de publicités
• Insights des publicités

L’API ne prend pas en charge les points de terminaison ne figurant pas dans la liste ci-dessus. Si vous prévoyez d’inclure des rapports provenant de Meta dans votre solution, consultez les Conditions générales de la plateforme Meta et les Politiques développeur·se concernant l’API Marketing.