Como recuperar cadastros

Existem três formas de ler cadastros: baixar TSV, ler em lotes e usar o Webhooks.

Permissões

É possível ler cadastros ou atualizações em tempo real:

  • Usando um Token de Acesso à Página, ou seja, o token de acesso do administrador da página. Se você tiver, pelo menos, permissões de nível de anunciante na conta de anúncios associada ao anúncio de cadastro, o token de acesso à página também permitirá a leitura de campos específicos de anúncios, como ad_id, campaign_id.
  • Usando o Token de Acesso do Usuário que pertence ao administrador da página. Para acessar todos os dados de cadastro e em nível de anúncios, o token de acesso deve ter o escopo manage_pages e ads_management.

Para recuperar informações de cadastro depois que um ID de cadastro é recebido pelo Webhooks, você também deverá solicitar a permissão da API de Recuperação de Cadastros leads_retrieval, além da permissão manage_pages, e enviar seu aplicativo para Análise do Aplicativo.

Não enviaremos mais dados coletados nos formulários de anúncios de cadastro pelo Webhooks para aplicativos no Modo de Desenvolvimento. Essa alteração entrará em vigor em 1º de fevereiro de 2019.

Gerencie os direitos de usuário por meio das funções na Página.

Baixar TSV

Outra opção é consultar diretamente o formulário de geração de cadastros. Observe que o campo está identificado como leadgen_export_csv_url embora o único formato compatível seja 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>

Resposta:

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

Como filtrar

Opcionalmente, você pode filtrar a resposta do URL para baixar os cadastros de um determinado intervalo de datas. Use from_date e to_date no formato de data POSIX ou UNIX, expressando o número de segundos desde o epoch. Por exemplo, para baixar os cadastros do período que inicia em 13/01/2016 às 18h20min31s UTC e encerra em 14/01/2016 às 18h20min31s 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 from_date não estiver definido ou se for um valor anterior ao horário de criação do formulário, o horário de criação do formulário será usado.
  • Se to_date não estiver definido ou se for um carimbo de data/hora posterior ao horário atual, o horário atual será usado.

Se alguma entrada não tiver um ID do Anúncio ou ID do Grupo de anúncios no TSV, será por um dos seguintes motivos:

  • O cadastro foi gerado pelo alcance orgânico. Nesse caso, is_organic no TSV exibe 1. Caso contrário, o valor é 0.
  • O cadastro pode ter sido enviado de uma Prévia do Anúncio.
  • Alguém que baixou cadastros não tem privilégios de Anunciante na Conta de Anúncios que está executando o Anúncio de Cadastro.

Ler em lotes

O parâmetro leads existe no grupo de anúncios e nos nós do formulário. Ele retorna todos os dados associados aos seus respectivos objetos. Como é possível reutilizar um formulário para muitos anúncios, seu formulário poderá ser usado por muito mais cadastros do que um só anúncio.

Para fazer a leitura em lotes por anúncio:

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

Para fazer a leitura por formulário:

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

A resposta:

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

Como ler um valor de pergunta do Localizador de Lojas

A pergunta do localizador de lojas não é diferente de nenhuma outra. Uma pergunta de localizador de lojas também terá um ID de campo que será mapeado em relação a eles durante a criação do formulário. Elas também serão enviadas de modo semelhante a outras perguntas. O valor passado virá do Número da Loja da localização selecionada.

Por exemplo, digamos que você tem uma pergunta do localizador de lojas com o ID de campo selected_dealer. Para buscar os cadastros em massa, você poderia chamar:

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

A resposta:

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

Como ler respostas de avisos legais personalizados

O parâmetro field_data não contém as respostas das caixas de seleção opcionais de avisos legais personalizados que o usuário preencheu. Para recuperar as respostas, é possível usar o campo custom_disclaimer_responses.

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

Resposta:

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

Como filtrar cadastros

Este exemplo filtra os cadastros com base nos carimbos de data/hora. A data/hora deve estar no 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

Geração de tokens

Se o formulário tiver IDs de campo personalizados, os campos e valores retornados serão os campos e valores especificados.

Webhooks

Veja atualizações em tempo real enquanto os cadastros são preenchidos. Confira o Vídeo Anúncios de Cadastro com Webhooks.

Muitos CRMs fornecem atualizações em tempo real para migrar dados de anúncios de Cadastro para os CRMs. Consulte Integrações de CRM disponíveis.

Configuração

1. Configurar endpoint para controlar pings em tempo real

O ping para as atualizações em tempo real é estruturado conforme abaixo. Saiba mais no Blog de atualizações em tempo real.

Várias modificações podem surgir pelo ping na matriz de alterações.

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

Você pode usar leadgen_id para recuperar dados associados ao cadastro:

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

A resposta:

{
  "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. Assinar eventos de geração de cadastros para o aplicativo

Para assinar o evento leadgen, seu usuário deverá responder com solicitações HTTP GET conforme descrito em Como receber atualizações da API em tempo real com o Webhooks.

Depois de configurar seu URL de retorno de chamada, assine o Webhook leadgen no Painel dos seus aplicativos ou por meio de uma chamada API:

Para assinar por meio da API, você precisa de um token de acesso do aplicativo, e não de um token de acesso de usuário:

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. Obter token da página

Gere um token único e de vida longa para a página para buscar dados de maneira contínua sem se preocupar com a expiração:

  1. Obtenha um token de usuário normal.
  2. Converta em um token de vida longa.
  3. Com o token de acesso de usuário de vida longa, solicite o token da página:
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: { }, })

A resposta:

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

Esse token de vida longa para a página não tem data de expiração, e você pode embutir no código integrações simples de direito de uso para reunir dados de cadastros.

4. Assinar a página para o aplicativo

Com o access_token para a página que você precisa assinar, faça a chamada a seguir para autenticar um aplicativo na sua página. É necessário ter no mínimo a permissão MODERATE_CONTENT da página para realizar essa ação.

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

O aplicativo do Facebook associado ao seu token é autenticado para as atualizações da página. Não é necessário especificar o ID do aplicativo.

Em caso de sucesso, os pings em tempo real ocorrem nos eventos com um atraso de no máximo alguns minutos. Consulte a Solução de problemas de integrações em tempo real.