リードの取得

リードを読み込む3つの方法があります。TSVダウンロード、一括読み込みおよびWebhooksの使用です。

アクセス許可

以下の方法で、リードまたはリアルタイムアップデートを読み込むことができます。

  • ページアクセストークン(つまり、ページ管理者のページに対するアクセストークン)を使用する。リード広告に関連付けられている広告アカウントに対して、広告主またはそれ以上のレベルのアクセス許可を保持している場合、ページアクセストークンを使用してad_idcampaign_idなどの広告固有のフィールドも読み込むことができます。
  • ページ管理者に属するユーザーアクセストークンを使用する。すべてのリードデータおよび広告レベルデータにアクセスするには、アクセストークンにmanage_pagesおよびads_managementのスコープが必要です。

Webhooks経由でリードIDを受け取った後にリード情報を取得するには、リード取得APIのleads_retrievalアクセス許可とmanage_pagesアクセス許可をリクエストして、アプリレビューにアプリを申請する必要もあります。

Devモードで、リード広告フォームで収集したデータをアプリにWebhooks経由で送信することは停止する予定です。この変更は、2019年2月1日から実施します。

ユーザー権限は、ページの役割で管理できます。

TSVダウンロード

特定のリード獲得フォームを直接クエリできます。サポートされている形式は TSVだけですが、フィールドのラベルはleadgen_export_csv_urlとなっていることに注意してください。

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>

応答は次のようになります。

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

フィルター処理

オプションで、URL応答をフィルター処理して特定の期間のリードをダウンロードできます。from_dateto_dateを、開始日からの秒数で表すPOSIXまたはUNIXの時間形式で指定します。たとえば、2016-01-13 18:20:31 UTCから2016-01-14 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

注:

  • from_dateに値が設定されていない場合や、フォーム作成時刻よりも前の値が設定されている場合は、フォーム作成時刻が使用されます。
  • to_dateに値が設定されていない場合や、現在の時刻よりも後のタイムスタンプが設定されている場合は、現在の時刻が使用されます。

TSV内のエントリに広告IDまたは広告グループIDが含まれない場合、次の理由が考えられます。

  • リードがオーガニックリーチから獲得された。この場合、TSVのis_organicは1になります。それ以外の場合は0です。
  • リードが広告プレビューから送信された。
  • リードをダウンロードした人が、リード獲得広告を実行している広告アカウントで広告管理者特権を持っていない。

一括読み込み

leadsは、広告グループとフォームノードの両方にあります。一括読み込みでは、それぞれのオブジェクトに関連付けられたすべてのデータが返されます。フォームは多くの広告で再利用できるため、フォームには、それを使用した広告よりもずっと多くのリードが含まれていることがあります。

広告ごとに一括で読み込むには次のようにします。

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

フォームごとに読み込むには次のようにします。

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

応答は次のようになります。

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

店舗検索のための質問の値の読み取り

店舗検索のための質問はその他の質問と変わりません。店舗検索のための質問には、フォームの作成時にそれらの質問にマッピングされるフィールドIDもあります。これらのIDも、他の質問と同様に送信されます。受け渡される値は、選択した位置情報の店舗番号から取得されます。

たとえば、フィールドIDとしてselected_dealerが指定された店舗検索のための質問があるとします。次のように呼び出すことで、リードを一括してフェッチできます。

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

応答は次のようになります。

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

カスタム免責事項の応答の読み込み

field_dataには、ユーザーが任意でチェックを入れたカスタム免責事項チェックボックスへの応答は含まれません。この応答を取得するには、custom_disclaimer_responsesフィールドを使用します。

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

応答は次のようになります。

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

リードのフィルター処理

次の例は、タイムスタンプに基づいてリードをフィルター処理します。タイムスタンプには、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

トークン化

フォームにカスタマイズされたフィールドIDが含まれる場合、返されるフィールドと値は、指定されたフィールドと値です。

Webhooks

リードが入力されたときにリアルタイムでアップデートを取得します。Webhooksによるリード獲得広告(動画)を参照してください。

多くのCRMでは、リード広告データをCRMに移動する際に、リアルタイムアップデートができます。利用可能なCRM統合を参照してください。

セットアップ

1. リアルタイムのpingを処理するためのエンドポイントをセットアップする

リアルタイムアップデートのためのpingの構造は次のようになります。詳細は、Real Time Updates (ブログ)を参照してください。

pingにより、changes配列で複数の変更を取得できます。

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

leadgen_idを使用して、リードと関連付けられているデータを取得できます。

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

応答は次のようになります。

{
  "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イベントに登録する

leadgenイベントに登録するには、WebhooksによりAPIアップデートをリアルタイムで取得するで説明されているように、サーバーがHTTPGETリクエストで応答する必要があります。

コールバックURLを設定したら、アプリのダッシュボード、またはAPI呼び出しを使用してleadgen webhookに登録します。

APIを使って登録するには、ユーザーアクセストークンではなくアプリアクセストークンが必要です

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. ページトークンの取得

単一の長期ページトークンを生成して、期限を気にすることなくデータを継続的にフェッチするには次のようにします。

  1. 通常のユーザートークンを取得します。
  2. それを長期トークンに変換します。
  3. 長期のユーザーアクセストークンを使用して、ページトークンをリクエストします。
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: { }, })

応答は次のようになります。

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

この長期ページトークンに有効期限はなく、シンプルなRTU統合にハードコードしてリードデータを取得できます。

4. ページをアプリに登録する

登録したいページのaccess_tokenを使用して次の呼び出しを実行し、ページに対してアプリを認証します。このアクションを実行するには、少なくともページに対するMODERATE_CONTENTアクセス許可が必要です。

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

トークンと関連付けられたFacebookアプリが、ページのアップデートに関して認証されます。アプリIDを指定する必要はありません。

成功すると、イベントに対してリアルタイムのpingが実行されます。これには最大で数分の遅延があります。リアルタイム統合のトラブルシューティングを参照してください。