Recuperación de clientes potenciales

Existen tres métodos para leer información sobre los clientes potenciales: descarga de TSV, lectura masiva y Webhooks.

Permisos

Puedes leer sobre clientes potenciales o actualizaciones en tiempo real mediante:

  • Un token de acceso a la página, específicamente, el token de acceso a la página del administrador para esa página. El token de acceso a la página también permite leer campos específicos de anuncios, como ad_id, campaign_id, si tienes permisos al menos en el nivel de anunciante en la cuenta publicitaria asociada con el anuncio para clientes potenciales.
  • Un token de acceso de usuario que pertenezca al administrador de la página. Para acceder a todos los datos de nivel de anuncios y de clientes potenciales, el token de acceso debe tener los tipos de alcance manage_pages y ads_management.

Para recuperar información sobre clientes potenciales después de haber recibido el identificador del cliente potencial a través de Webhooks, también debes solicitar permiso para la API de recuperación de clientes potenciales leads_retrieval y permiso manage_pages, y enviar tu aplicación a la revisión de aplicaciones.

Dejaremos de enviar datos recopilados en los formularios de anuncios para clientes potenciales mediante Webhooks a las aplicaciones en Dev Mode. El cambio estará vigente a partir del 1 de febrero de 2019.

Puedes administrar los derechos de usuario mediante roles de página.

Descarga de TSV

Puedes consultar directamente un formulario específico de generación de clientes potenciales: Ten en cuenta que el campo está etiquetado leadgen_export_csv_url, aunque el único formato que se admite es 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>

Respuesta:

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

Filtrado

De manera opcional, puedes filtrar la respuesta de la dirección URL para descargar clientes potenciales de un intervalo de fechas especificado. Usa from_date y to_date en un formato de hora POSIX o UNIX que exprese el número de segundos desde la fecha de inicio. Por ejemplo, para descargar clientes potenciales del período desde el 13-01-2016 a las 18:20:31 UTC hasta el 14-01-2016 a las 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:

  • Si from_date no se configuró o es anterior a la hora de creación del formulario, se usará la hora de creación del formulario.
  • Si to_date no se configuró o es una marca de tiempo posterior a la hora actual, se usará la hora actual.

Si alguna entrada no tiene el identificador del anuncio o del grupo de anuncios en el TSV, puede deberse a los siguientes motivos:

  • El cliente potencial se genera a partir del alcance orgánico. En este caso, el parámetro is_organic del TSV muestra 1. De lo contrario, el valor es 0.
  • El cliente potencial puede enviarse desde una vista previa del anuncio.
  • Cualquiera que descargue clientes potenciales carece de privilegios de anunciante sobre la cuenta publicitaria que ejecuta el anuncio para clientes potenciales.

Lectura masiva

El parámetro leads existe tanto en grupos de anuncios como en nodos de formulario. Este devuelve todos los datos asociados a sus respectivos objetos. Dado que un formulario puede reutilizarse para muchos anuncios, el formulario puede contener muchos más clientes potenciales que un anuncio que lo utilice.

Para la lectura masiva por anuncio:

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 la lectura por formulario:

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

La respuesta:

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

Lectura de valor de pregunta de localizador de tiendas

La pregunta del localizador de tiendas no es distinta de otras preguntas. Una pregunta del localizador de tiendas tiene un identificador de campo que se les asigna durante la creación del formulario. También se envían de manera similar a otras preguntas. El valor aprobado viene del número de tienda de la ubicación seleccionada.

Por ejemplo, supongamos que hay una pregunta del localizador de tiendas con selected_dealer como identificador de campo. Para recibir el conjunto de clientes potenciales puedes hacer la siguiente llamada:

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

La respuesta:

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

Lectura de respuestas del descargo de responsabilidad personalizado

El parámetro field_data no contiene las respuestas a las casillas de descargo de responsabilidad personalizado que el usuario habría completado. Para recuperar las respuestas, puedes utilizar el campo custom_disclaimer_responses.

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

Respuesta:

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

Filtro de clientes potenciales

En este ejemplo, se filtran los clientes potenciales en función de las marcas de tiempo. Las marcas de tiempo deben ser 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

Tokenización

Si el formulario tiene identificadores de campo personalizados, los campos y los valores devueltos serán los campos y los valores especificados.

Webhooks

Obtén actualizaciones en tiempo real cuando se completen los clientes potenciales. Consulta el video sobre anuncios para clientes potenciales con webhooks.

Muchas soluciones de CRM proporcionan actualizaciones en tiempo real para migrar a ellas los datos de anuncios para clientes potenciales. Consulta Integración con CRM disponible.

Configuración

1. Configurar el extremo para controlar pings en tiempo real

El ping para las actualizaciones en tiempo real está estructurado como se indica a continuación. Obtén más información en Actualizaciones en tiempo real, Blog.

Es posible que se produzcan varios cambios mediante el ping en la matriz de cambios.

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

Puedes utilizar leadgen_id para recuperar los datos asociados al cliente potencial:

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

La respuesta:

{
  "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. Suscribir la aplicación a eventos de generación de clientes potenciales

Para la suscripción al evento leadgen, el servidor debe responder con solicitudes HTTP GET, como se describe en Recepción de actualizaciones de la API en tiempo real con Webhooks.

Después de configurar la URL de devolución de llamada, suscríbete al Webhook leadgen en el panel de la aplicación o a través de una llamada a la API:

Para suscribirte a través de la API, necesitas un token de acceso a la aplicación, no un token de acceso de usuario:

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. Obtener el token de página

Genera un token de página de larga duración único para recuperar datos continuamente sin preocuparte por la caducidad:

  1. Obtén un token de usuario normal.
  2. Conviértelo en un token de larga duración.
  3. Con el token de acceso de usuario de larga duración, solicita el token de 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: { }, })

La respuesta:

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

Este token de página de larga duración no tiene fecha de caducidad, y puedes codificarlo de manera rígida en integraciones de RTU simples para obtener datos de clientes potenciales.

4. Suscribir la página a la aplicación

Con el access_token de la página que tienes que suscribir, realiza la llamada que se muestra a continuación para autenticar una aplicación para tu página. Debes tener, como mínimo, el permiso MODERATE_CONTENT para la página a fin de poder realizar esta acción.

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

La aplicación de Facebook asociada a tu identificador está autenticada para las actualizaciones de página; no es necesario que especifiques un identificador de la aplicación.

Si la acción se realiza correctamente, los pings en tiempo real tienen lugar en eventos con un retraso que puede ser de hasta unos pocos minutos. Consulta Solución de problemas de integración en tiempo real.