Recuperación de clientes potenciales

Existen tres métodos para la lectura de clientes potenciales: descarga de TSV, lectura masiva y webhooks.

Permisos

Las actualizaciones en tiempo real o de clientes potenciales se pueden consultar de las siguientes maneras:

  • Mediante un identificador de acceso a la página, es decir, el identificador de acceso que el administrador de la página asigna a la página. Un identificador de acceso a la página también te permite leer campos específicos de los anuncios, como ad_id, campaign_id, etc., siempre que tengas los permisos de nivel de anunciante como mínimo en la cuenta publicitaria asociada al anuncio para clientes potenciales.
  • Mediante el identificador de acceso de usuario perteneciente al administrador de la página. Para acceder a todos los datos de clientes potenciales y a los datos de nivel de anuncio, el identificador de acceso debe tener los ámbitos manage_pages y ads_management.

Para recuperar la información de clientes potenciales después de recibir el identificador de cliente potencial a través de webhooks, también debes solicitar los permisos leads_retrieval y manage_pages de la API de recuperación de clientes potenciales y enviar tu aplicación al proceso de revisión de aplicaciones.

Dejaremos de enviar los datos recopilados en formularios de anuncios para clientes potenciales mediante webhooks a las aplicaciones en modo de desarrollo. Este cambio se aplicará 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. Observa que el campo presenta la etiqueta leadgen_export_csv_url, aunque el único formato admitido 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"
}

Filtración

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 de tiempo 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 ha establecido 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 ha establecido o es una marca de tiempo posterior a la hora actual, se usará la hora actual.

Si alguna entrada carece del 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 se puede enviar 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 se puede reutilizar 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 un valor de pregunta de localizador de negocios

La pregunta de localizador de negocios no es diferente de cualquier otra pregunta. Una pregunta de localizador de negocios también tendrá un identificador de campo que se asignará a estos durante la creación del formulario. También se enviará de manera parecida a otras preguntas. El valor pasado procederá del número de negocio de la ubicación seleccionada.

Por ejemplo, supongamos que tienes una pregunta de localizador de negocio con el identificador de campo selected_dealer. Para recuperar los clientes potenciales de forma masiva, puedes realizar 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 de descargo de responsabilidad personalizadas

El parámetro field_data no contiene las respuestas a las casillas de declinación de descargo de responsabilidad que el usuario habría rellenado. Para recuperar las respuestas, puedes usar 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"
}

Filtración 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 rellenen los clientes potenciales. Consulta el vídeo sobre anuncios para clientes potenciales con webhooks.

Muchos CRM proporcionan actualizaciones en tiempo real para migrar a estos los datos de anuncios para clientes potenciales. Consulta el tema sobre integración de 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 la publicación sobre actualizaciones en tiempo real en el blog (en inglés).

Es posible que se produzcan varios cambios a través del 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 usar 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, tal como se describe en el artículo sobre la recepción de actualizaciones de la API en tiempo real con webhooks.

Una vez configurada 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 identificador de acceso a la aplicación, no un identificador 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 identificador de página

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

  1. Obtén un identificador de usuario normal.
  2. Conviértelo en un identificador de larga duración.
  3. Con el identificador de acceso de usuario de larga duración, solicita el identificador 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 identificador 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 siguiente 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 ningún 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 el tema sobre solución de problemas de integración en tiempo real.