Récupération des prospects

Il existe trois manières de récupérer les prospects : via le téléchargement d’un fichier TSV, la récupération groupée ou la fonctionnalité Webhooks.

Autorisations

Vous pouvez récupérer les prospects ou les mises à jour en temps réel selon les manières suivantes :

  • En utilisant un token d’accès de Page, c’est-à-dire le token d’accès de l’administrateur de la Page demandée. Le token d’accès de Page vous permet également de récupérer des champs de publicité spécifiques, tels que ad_id, campaign_id, tant que vous disposez au minimum des autorisations de niveau annonceur pour le compte publicitaire associé à la publicité à formulaire.
  • En utilisant un token d’accès utilisateur appartenant à l’administrateur de la Page. Pour accéder à l’ensemble des données de prospection et des données au niveau de la publicité, vous devez disposer d’un token d’accès associé aux champs d’application manage_pages et ads_management.

Pour récupérer les informations de prospection après avoir reçu un ID de prospect via Webhooks, vous devez également demander l’autorisation leads_retrieval à l’API Lead Retrieval, ainsi que l’autorisation manage_pages et soumettre votre app à un Contrôle app.

Nous arrêterons d’envoyer des données collectées dans les formulaires Lead Ads via Webhooks aux apps en Mode développeur. Nous commencerons à appliquer cette modification le 1er février 2019.

Vous pouvez gérer vos droits utilisateur via les rôles sur la Page.

Téléchargement de fichier TSV

Vous pouvez demander directement à récupérer un formulaire génération de prospects spécifique. Notez que même si le champ est libellé leadgen_export_csv_url, seul le format TSV est accepté.

use FacebookAds\Object\LeadgenForm;

$form = new LeadgenForm(<FORM_ID>);
$form->read();
from facebookads.adobjects.leadgenform import LeadgenForm

form = LeadgenForm(<LEADGEN_FORM_ID>)
form.remote_read()
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<FORM_ID>

Réponse :

{
  "id": "<LEAD_GEN_FORM_ID>",
  "leadgen_export_csv_url": "https://www.facebook.com/ads/lead_gen/export_csv?type=form&amp;id=<FORM_ID>",
  "locale": "en_US",
  "name": "My Form",
  "status": "ACTIVE"
}

Filtrage

Si vous le souhaitez, vous avez la possibilité de filtrer la réponse URL afin de télécharger des prospects pour une plage de dates spécifique. Utilisez from_date ou to_date au format temporel POSIX ou UNIX, en spécifiant le nombre de secondes depuis la date de création. Par exemple, si vous voulez télécharger les prospects pour la période allant du 2016-01-13 18:20:31 UTC au 2016-01-14 18:20:31 UTC :

https://www.facebook.com/ads/lead_gen/export_csv/?id=<FORM_ID>&amp;type=form&amp;from_date=1482698431&amp;to_date=1482784831

Remarque :

  • Si le paramètre from_date n’est pas défini ou contient une valeur antérieure à la date de création du formulaire, cette dernière est utilisée.
  • Si le paramètre to_date n’est pas défini ou contient une valeur postérieure à la date actuelle, cette dernière est utilisée.

Il est possible que certaines entrées du fichier TSV ne contiennent pas d’ID publicité ni d’ID de groupe publicitaire, pour l’une des raisons suivantes :

  • Le prospect est issu de la publicité organique. Dans ce cas, le paramètre is_organic affiche la valeur 1 dans le fichier TSV. Sinon, il affiche la valeur 0.
  • Le prospect est associé à l’aperçu de la publicité.
  • L’utilisateur qui procède au téléchargement des prospects ne dispose pas des privilèges Annonceur pour le compte publicitaire qui diffuse la publicité à formulaire.

Récupération groupée

Le paramètre leads existe au niveau des nœuds du groupe publicitaire et du formulaire. Il renvoie toutes les données associées à leurs objets spécifiques. Étant donné qu’un formulaire peut être réutilisé dans de nombreuses publicités, celui-ci peut générer beaucoup plus de prospects qu’une pub qui l’a diffusé.

Pour récupérer les prospects de manière groupée par pub :

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$leads = $ad->getLeads();
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
leads = ad.get_leads()
APINodeList<Lead> leads = new Ad(<AD_ID>, context).getLeads()
  .execute();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/leads

Pour récupérer les prospects par formulaire :

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'fields=created_time,id,ad_id,form_id,field_data' \
https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

Réponse :

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

Lecture d’une valeur de question de la carte des boutiques

Une question de la carte des boutiques n’est pas différente d’une autre question. Une question de carte des boutiques possédera également un ID de champ mappé avec les autres questions lors de la création du formulaire. Elles seront envoyées de la même façon que les autres questions. La valeur transmise émanera du Numéro du magasin du lieu sélectionné.

Par exemple, supposons qu’une question de la carte des boutiques possède selected_dealer comme ID de champ. Pour récupérer les prospects en bloc, vous pouvez appeler :

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'fields=created_time,id,ad_id,form_id,field_data' \
https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

Réponse :

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
        {
          "name": "selected_dealer", 
          "values": [
            "99213450"
          ]
        }
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

Récupération des réponses aux cases à cocher dans les avis de limitation de responsabilité personnalisés

Le champ field_data ne contient pas les réponses aux cases que l’utilisateur peut cocher dans les avis de limitation de responsabilité personnalisés. Pour les récupérer, vous pouvez utiliser le champ custom_disclaimer_responses.

curl \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<LEAD_ID>?fields=custom_disclaimer_responses"

Réponse :

{
  "custom_disclaimer_responses": [
    {
      "checkbox_key": "optional_1",
      "is_checked": "1"
    },
    {
      "checkbox_key": "optional_2",
      "is_checked": ""
    }
  ],
  "id": "1231231231"
}

Filtrage des prospects

Dans cet exemple, les prospects sont filtrés en fonction de l’horodatage (au format Unix).

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdReportRunFields;

$ad = new Ad(<AD_ID>);
$time_from = (new \DateTime("-1 week"))->getTimestamp();
$leads = $ad->getLeads(array(), array(
  AdReportRunFields::FILTERING => array(
    array(
      'field' => 'time_created',
      'operator' => 'GREATER_THAN',
      'value' => $time_from,
    ),
  ),
));
curl -G \
  --data-urlencode 'filtering=[ 
    { 
      "field": "time_created", 
      "operator": "GREATER_THAN", 
      "value": 1516682744 
    } 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/leads

Tokenisation

Si le formulaire comporte des ID de champs personnalisés, les champs et les valeurs renvoyés seront ceux spécifiés par les ID.

Webhooks

Vous pouvez recevoir des mises à jour en temps réel lorsque des prospects sont générés. Visualisez la vidéo Publicités à formulaire avec Webhooks.

De nombreux CRM fournissent des mises à jour en temps réel afin d’intégrer les données des publicités à formulaire dans le système. Consultez la page Intégrations à un système CRM disponibles.

Configuration

1. Configurer un point de terminaison pour gérer les pings en temps réel

Le ping de mise à jour en temps réel est structuré comme suit. Pour en savoir plus, lisez l’article de blog Real Time Updates (en anglais).

Le ping peut renvoyer une matrice comportant plusieurs modifications.

array(
  "object" => "page",
  "entry" => array(
    "0" => array(
      "id" => 153125381133,
      "time" => 1438292065,
      "changes" => array(
        "0" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123123,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        ),
        "1" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123124,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        )
      )
    )
  )
)

Vous pouvez utiliser le paramètre leadgen_id pour récupérer des données associées au prospect :

curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/{lead-id}/
const adsSdk = require('facebook-nodejs-ads-sdk'); const Lead = adsSdk.Lead; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { }; let sample_code = (new Lead(id)).get( fields, params ); logApiCallResult('sample_code api call complete.', sample_code);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Lead; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new Lead($id))->getSelf( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.lead import Lead from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print Lead(id).get( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Lead(id, context).get() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end lead = FacebookAds::Lead.get(id ,'')

Réponse :

{
  "created_time": "2015-02-28T08:49:14+0000", 
  "id": "<LEAD_ID>", 
  "ad_id": "<AD_ID>",
  "form_id": "<FORM_ID>",
  "field_data": [{
    "name": "car_make",
    "values": [
      "Honda"
    ]
  }, 
  {
    "name": "full_name", 
    "values": [
      "Joe Example"
    ]
  }, 
  {
    "name": "email", 
    "values": [
      "joe@example.com"
    ]
  },
  {
    "name": "selected_dealer", 
    "values": [
      "99213450"
    ]
  }],
  ...
}

2. Abonner l’app aux évènements de génération de prospects

Pour abonner l’app à l’évènement leadgen, il faut que votre serveur renvoie des requêtes HTTP GET (voir Réception de mises à jour de l’API en temps réel avec Webhooks).

Une fois que votre URL de rappel est configurée, abonnez l’app au webhook leadgen dans le tableau de bord ou via un appel à l’API :

Dans le second cas, il vous faudra un token d’accès d’app, et non un token d’accès d’utilisateur :

curl \
-F "object=page" \
-F "callback_url=https://www.yourcallbackurl.com" \
-F "fields=leadgen" \
-F "verify_token=abc123" \
-F "access_token=<APP_ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<APP_ID>/subscriptions"

3. Obtenir le token de la page

Générez un token de page longue durée pour récupérer les données en continu, sans vous soucier de son expiration.

  1. Procurez-vous un token d’utilisateur standard.
  2. Convertissez-le en token longue durée.
  3. Avec celui-ci, demandez le token d’accès de la page :
curl -X GET \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.1/{user-id}/accounts
const adsSdk = require('facebook-nodejs-ads-sdk'); const User = adsSdk.User; const Page = adsSdk.Page; let access_token = '<ACCESS_TOKEN>'; let app_secret = '<APP_SECRET>'; let app_id = '<APP_ID>'; let id = '<ID>'; const api = adsSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { }; let accountss = (new User(id)).getAccounts( fields, params ); logApiCallResult('accountss api call complete.', accountss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\User; use FacebookAds\Object\Page; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new User($id))->getAccounts( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.user import User from facebookads.adobjects.page import Page from facebookads.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print User(id).get_accounts( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new User(id, context).getAccounts() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end user = FacebookAds::User.get(id) accountss = user.accounts({ fields: { }, })

Réponse :

{
  "data": [
    {
      "access_token": "[REDACTED]",
      "category": "Pet",
      "name": "Puppy",
      "id": "153125381133",
      "perms": [
        "ADMINISTER",
        "EDIT_PROFILE",
        "CREATE_CONTENT",
        "MODERATE_CONTENT",
        "CREATE_ADS",
        "BASIC_ADMIN"
      ]
    },
  ]
}

Ce token longue durée n’a pas de date d’expiration, et vous pouvez le coder en dur dans des intégrations simples de mise à jour en temps réel pour récupérer les données des prospects.

4. Abonner la page à l’app

Avec le access_token de la page à laquelle vous devez vous abonner, envoyez l’appel ci-dessous pour authentifier l’app. Vous devez posséder au moins une autorisation MODERATE_CONTENT pour la page pour effectuer cette action.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

Api::instance()->call(
  '/' . <PAGE_ID> . '/subscribed_apps',
  RequestInterface::METHOD_POST);
curl \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PAGE_ID>/subscribed_apps

L’app Facebook associée à votre token est authentifiée pour les mises à jour de la page. Vous n’avez pas besoin de spécifier l’ID d’app.

Si l’opération est un succès, des pings de mise à jour en temps réel sont envoyés aux évènements au bout de quelques minutes. Consultez la page Résolution des erreurs d’intégration pour les mises à jour en temps réel.