Abrufen von Leads

Du kannst Leads auf drei Arten lesen: mit TSV-Download, Pulk-Erfassung oder Webhooks.

Berechtigungen

Du kannst Leads oder Echtzeit-Updates folgendermaßen lesen:

  • Mit einem Seiten-Zugriffsschlüssel, d. h. dem Zugriffsschlüssel des Seitenadministrators für die Seite. Mithilfe von Seiten-Zugriffsschlüsseln kannst du außerdem anzeigenspezifische Felder wie ad_id, campaign_id usw. lesen, wenn du für das Werbekonto, das mit dem Lead Ad verknüpft ist, mindestens über Berechtigungen auf Werbetreibenden-Ebene verfügst.
  • Mit einem Nutzer-Zugriffsschlüssel, der dem Seitenadministrator gehört. Um auf alle Lead-Daten und die Daten auf Anzeigenebene zuzugreifen, sollte der Zugriffsschlüssel manage_pages und ads_management umfassen.

Um Lead-Informationen abzurufen, nachdem über Webhooks eine Lead-ID empfangen wurde, musst du auch die Lead-Abruf-API-Berechtigung leads_retrieval sowie die Berechtigung manage_pages anfordern und deine App an App Review senden.

Wir senden keine weiteren in Lead Ads-Formularen erfassten Daten über Webhooks an Apps im Entwicklungsmodus. Diese Änderung tritt am 1. Februar 2019 in Kraft.

Du kannst die Nutzerrechte mit Seitenrollen verwalten.

TSV-Download

Du kannst auch direkt ein spezielles Formular zur Leadgenerierung abfragen. Beachte, dass das Feld mit leadgen_export_csv_url gekennzeichnet ist, obwohl nur das Format TSV unterstützt wird.

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>

Antwort:

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

Filtern

Optional kannst du die URL-Antwort für den Download von Leads aus einem bestimmten Datumsbereich filtern. Verwende from_date und to_date im Zeitformat POSIX oder UNIX und gib die Anzahl der Sekunden seit Beginn an. So lädst du zum Beispiel Leads für einen Zeitraum herunter, der am 13.01.2016 um 18:20:31 (UTC) beginnt und am 14.01.2016 um 18:20:31 (UTC) endet:

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

Hinweis:

  • Wenn from_date nicht festgelegt wurde oder einen Wert hat, der geringer als der Erstellungszeitpunkt des Formulars ist, wird der Erstellungszeitpunkt des Formulars verwendet.
  • Wenn to_date nicht festgelegt wurde oder der Zeitstempel vor dem aktuellen Zeitpunkt liegt, wird der aktuelle Zeitpunkt verwendet.

Wenn für Einträge die Anzeigen-IDs oder Anzeigengruppen-IDs in TSV fehlen, kann das folgende Ursachen haben:

  • Der Lead wird aus organischer Reichweite erstellt. Unter is_organic in TSV wird in diesem Fall 1 angezeigt. Ansonsten wird der Wert als 0 angezeigt.
  • Der Lead kann aus einer Anzeigenvorschau eingereicht werden.
  • Jemand, der Leads herunterlädt, verfügt nicht über Berechtigungen als Werbetreibender für das Werbekonto, über das die Lead Ad läuft.

Pulk-Erfassung

Der leads existiert sowohl in der Anzeigengruppe als auch in den Formularknoten. Dadurch werden alle mit den betreffenden Objekten verbundenen Daten übermittelt. Da ein Formular für mehrere Anzeigen verwendet werden kann, könnte dein Formular viel mehr Leads empfangen als eine Anzeige, die das Formular verwendet.

Mit Pulk-Erfassung nach Anzeige lesen:

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

Nach Formular lesen:

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

Antwort:

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

Lesen des Werts einer Filialsuchenfrage

Eine Filialsuchenfrage unterscheidet sich nicht von anderen Fragentypen. Auch eine Filialsuchenfrage hat eine Feld-ID, die während der Formularerstellung abgeglichen wird. Sie wird ähnlich wie andere Fragen gesendet. Der übergebene Wert stammt aus der Geschäftsnummer des ausgewählten Standorts.

Angenommen beispielsweise, du hast eine Filialsuchenfrage mit der Feld-ID selected_dealer. Um alle Leads gleichzeitig abzurufen, kannst du folgenden Aufruf verwenden:

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

Antwort:

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

Lesen von Antworten auf benutzerdefinierte Haftungsausschlüsse

Das field_data beinhaltet keine Antworten auf benutzerdefinierte Haftungsausschluss-Kontrollkästchen, die der Benutzer vielleicht angehakt hat. Du kannst die Antworten über das Feld custom_disclaimer_responses abrufen.

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

Antwort:

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

Filtern von Leads

Bei diesem Beispiel werden Leads nach Zeitstempeln gefiltert. Zeitstempel müssen im Unix-Format vorliegen.

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

Verschlüsselung

Wenn das Formular über benutzerdefinierte Feld-IDs verfügt, werden die benutzerdefinierten Felder und Werte übermittelt.

Webhooks

Erhalte Aktualisierungen in Echtzeit, wenn Leads ausgefüllt werden. Siehe Video zu Lead Ads mit Webhooks.

Viele CRMs bieten Aktualisierungen in Echtzeit für die Migration von Daten aus Lead Ads zu den CRMs. Siehe Verfügbare CRM-Integrationen.

Setup

1. Endpunkt zur Verarbeitung von Echtzeit-Pings einrichten

Das Ping für Aktualisierungen in Echtzeit ist wie im Folgenden aufgeführt strukturiert. Erfahre mehr im Blogeintrag zu Aktualisierungen in Echtzeit.

Mehrere Änderungen können über das Ping im Änderungen-Array eingehen.

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

Du kannst leadgen_id nutzen, um mit dem Lead verbundene Daten abzurufen:

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

Antwort:

{
  "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. leadgen-Events für App abonnieren

Damit du ein leadgen-Event abonnieren kannst, muss dein Server HTTP-GET-Anfragen wie in Empfangen von API-Aktualisierungen in Echtzeit mit Webhooks unterstützen.

Nachdem du deine Rückruf-URL eingerichtet hast, abonniere den leadgen-Webhook auf dem Dashboard deiner App oder durch einen API-Aufruf:

Um das Abonnement über die API vorzunehmen, benötigst du einen App-Zugriffsschlüssel, keinen Nutzer-Zugriffsschlüssel:

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. Seitenschlüssel anfordern

Erstelle einen einzelnen langlebigen Seitenschlüssel, mit dem du Daten kontinuierlich abrufen kannst, ohne dir darüber Sorgen zu machen, dass er ablaufen könnte:

  1. Fordere einen regulären Benutzerschlüssel an.
  2. Wandle ihn in einen langlebigen Schlüssel um.
  3. Fordere mit dem langlebigen Benutzer-Zugriffsschlüssel den Seitenschlüssel an:
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: { }, })

Antwort:

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

Dieser langlebige Seitenschlüssel hat kein Ablaufdatum. Du kannst ihn in einfache RTU-Integrationen einbinden, um Daten von Leads abzurufen.

4. App für Seite abonnieren

Führe den unten aufgeführten Aufruf mit dem access_token der Seite durch, die du abonnieren möchtest, um eine App für deine Seite zu authentifizieren. Du musst mindestens über eine MODERATE_CONTENT-Berechtigung für die Seite verfügen, um diese Handlung ausführen zu können.

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

Die mit deinem Schlüssel verbundene Facebook-App wird für Seitenaktualisierungen authentifiziert. Du musst keine App-ID angeben.

Wenn diese Handlung erfolgreich ausgeführt wurde, erhältst du Pings für Events mit einer möglichen Verzögerung von ein paar Minuten. Siehe Fehlerbehebung für Integrationen in Echtzeit.