Recupero dei contatti

Esistono tre modi di leggere i contatti: download del TSV, lettura di massa e con Webhooks.

Autorizzazioni

È possibile leggere contatti o aggiornamenti in tempo reale nei modi seguenti:

  • Usando un token d'accesso della Pagina, ovvero, il token d'accesso dell'amministratore della Pagina richiesta. Il token d'accesso della Pagina consente inoltre di leggere campi specifici dell'inserzionista, come ad esempio ad_id, campaign_id, purché si disponga almeno delle autorizzazioni di livello inserzionista sull'account pubblicitario associato all'inserzione per acquisizione contatti.
  • Usando il token d'accesso dell'utente appartenente all'amministratore della pagina. Per accedere a tutti i dati di contatto e ai dati al livello dell'inserzione, il token d'accesso deve avere come ambito manage_pages e ads_management.

Per recuperare le informazioni sui contatti quando viene ricevuto un ID contatto tramite Webhooks, devi richiedere anche l'autorizzazione dell'API Lead Retrieval leads_retrieval, nonché l'autorizzazione manage_pages e inviare la tua app per l'Analisi dell'app.

L'invio dei dati raccolti nei moduli delle inserzioni per acquisizione contatti tramite Webhooks alle app verrà interrotto in Dev Mode. Inizieremo ad applicare questa modifica il 1 febbraio 2019.

Puoi gestire i diritti utente con i ruoli nella Pagina.

Download del TSV

Puoi chiedere direttamente un modulo di generazione di contatti specifico. Il campo è etichettato leadgen_export_csv_url anche se l’unico formato supportato è TSV.

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>

Risposta:

{
  "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"
}

Applicazione dei filtri

Se lo desideri, puoi filtrare la risposta dell’URL per scaricare i contatti per un intervallo di date specifico. Usa from_date e to_date in un formato temporale POSIX o UNIX, che indica il numero di secondi da quel momento. Ad esempio, per scaricare i contatti per il periodo che va dal 13-01-2016 alle 18:20:31 UTC al 14-01-2016 alle 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

Nota:

  • Se il valore from_date non è impostato o è un valore inferiore al momento della creazione del modulo, viene usato il momento della creazione del modulo.
  • Se il valore to_date non è impostato o è una data e ora successiva a quella presente, viene usata la data e ora presente.

Se nel TSV sono presenti voci senza ID dell’inserzione o l’ID del gruppo di inserzioni, può essere dovuto alle seguenti ragioni:

  • Il contatto viene generato dalla copertura organica. is_organic nel TSV mostra 1 in questo caso. Altrimenti il valore è 0.
  • Il contatto può essere inviato da un’anteprima dell’inserzione.
  • Chi scarica i contatti non possiede i privilegi dell’inserzionista sull’account pubblicitario che esegue l’inserzione per acquisizione contatti.

Lettura di massa

leads esiste sul nodo sia del gruppo di inserzioni sia del modulo. Vengono restituiti tutti i dati associati ai rispettivi oggetti. Dato che un modulo può essere riutilizzato per più inserzioni, il tuo modulo può contenere molti più contatti di quelli utilizzati dall’inserzione.

Per effettuare la lettura di massa per inserzione:

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

Per effettuare la lettura per modulo:

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

Risposta:

{
  "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"
    }
  }
}

Lettura del valore della domanda dello strumento di localizzazione dei punti vendita

La domanda dello strumento di localizzazione dei punti vendita non è diversa da qualsiasi altra domanda. Una domanda dello strumento di localizzazione dei punti vendita avrà anche un ID di campo che verrà mappato sulla base di esse durante la creazione del modulo. Saranno inviati in modo simile ad altre domande. Il valore passato proverrà dal numero di punto vendita della posizione selezionata.

Ad esempio, supponiamo di avere una domanda dello strumento di localizzazione dei punti vendita con selected_dealer come ID del campo. Per recuperare i contatti in blocco puoi chiamare:

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

Risposta:

{
  "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"
    }
  }
}

Lettura delle risposte dell'esclusione di responsabilità personalizzata

I field_data non contengono le risposte per le caselle dell’esclusione di responsabilità personalizzata opzionale che l’utente deve spuntare. Per recuperare le risposte, puoi usare il campo custom_disclaimer_responses.

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

Risposta:

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

Come filtrare i contatti

Questo esempio filtra i contatti in base a data e ora. La data e l’ora devono essere in formato 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

Creazione di token

Se il modulo ha ID di campo personalizzati, i campi e i valori restituiti saranno campi e valori specifici.

Webhooks

Ottieni aggiornamenti in tempo reale quando i contatti sono completati. Vedi Inserzioni per acquisizione contatti con Webhooks, Video.

Molti CRM forniscono aggiornamenti in tempo reale per migrare i dati delle inserzioni per l’acquisizione di contatti nei CRM. Vedi Integrazione CRM disponibile.

Configurazione

1. Configura un endpoint per gestire ping in tempo reale

Il ping per gli aggiornamenti in tempo reale è strutturato come segue. Leggi di più sul blog Real Time Updates.

Attraverso il ping della matrice delle modifiche possono avvenire diverse modifiche.

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
          )
        )
      )
    )
  )
)

Puoi usare leadgen_id per recuperare i dati associati al contatto:

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 ,'')

Risposta:

{
  "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. Ricevi gli aggiornamenti nell’app sulle azioni di generazione di contatti

Per ricevere gli aggiornamenti sull’azione leadgen, il server deve rispondere con richieste HTTP GET come descritto in Ricezione di aggiornamenti all’API in tempo reale con Webhooks.

Dopo aver configurato l’URL di richiamata, ricevi gli aggiornamenti al webhook leadgen nella dashboard della tua app o attraverso una chiamata API:

Per ricevere gli aggiornamenti attraverso l'API ti occorre un token d'accesso dell'app, non un token d'accesso utente:

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. Ottieni un token per una pagina

Genera un singolo token per una pagina di lunga durata per recuperare continuamente i dati senza doverne controllare la scadenza:

  1. Ottieni un token utente regolare.
  2. Convertilo in un token di lunga durata
  3. con il token di accesso utente di lunga durata, richiedi il token per la pagina:
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: { }, })

Risposta:

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

Questo token per la pagina di lunga durata non ha una data di scadenza e puoi impostarlo come hardcoded in integrazioni RTU semplici per ottenere i dati sui contatti.

4. Ricevi gli aggiornamenti della pagina nell’app

Con il access_token per la pagina devi chiedere di ricevere gli aggiornamenti, effettuare la chiamata seguente per autenticare un’app per la tua pagina. Devi avere almeno l’autorizzazione MODERATE_CONTENT alla pagina per poter effettuare questa azione.

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 di Facebook associata al tuo token è autenticata per gli aggiornamenti della pagina; non devi specificare l’ID della pagina.

A operazione riuscita, i ping in tempo reale vengono applicati alle azioni con un ritardo massimo di alcuni minuti. Vedi Risoluzione dei problemi di integrazione in tempo reale.