잠재 고객 검색

잠재 고객을 읽는 데는 TSV 다운로드, 대량 읽기, 그리고 Webhooks 사용의 3가지 방법이 있습니다.

권한

잠재 고객이나 실시간 업데이트는 다음과 같은 방법으로 읽을 수 있습니다.

  • 페이지 액세스 토큰, 즉 페이지 관리자의 페이지 액세스 토큰을 사용합니다. 또한 잠재 고객 광고와 연결된 광고 계정에 대해 광고주 레벨 이상의 권한이 있을 경우 페이지 액세스 토큰을 사용하면 ad_id, campaign_id 등의 광고별 필드를 읽을 수 있습니다.
  • 페이지 관리자가 가진 사용자 액세스 토큰을 사용합니다. 모든 잠재 고객 데이터와 광고 수준 데이터에 액세스하려면 액세스 토큰에 manage_pagesads_management 범위가 설정되어 있어야 합니다.

잠재 고객 정보를 검색하려면 Webhooks를 통해 잠재 고객 ID를 수신한 다음, 잠재 고객 검색 API leads_retrieval 권한과 manage_pages 권한을 요청하고 앱을 앱 검수에 제출해야 합니다.

Facebook은 Webhooks를 통해 잠재 고객용 광고 양식에서 수집된 데이터를 개발자 모드로 앱에 전송하는 것을 중단합니다. 이 변경 사항은 2019년 2월 1일부터 적용됩니다.

페이지 역할로 사용자 권한을 관리할 수 있습니다.

TSV 다운로드

특정 잠재 고객 생성 양식을 직접 쿼리할 수 있습니다. 참고로 필드는 leadgen_export_csv_url로 표시되지만 지원되는 유일한 형식은 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>

응답:

{
  "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_datePOSIX 또는 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가 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. 실시간 핑을 처리할 엔드포인트 설정

실시간 업데이트의 핑은 다음과 같이 구성됩니다. 자세한 정보는 실시간 업데이트, 블로그를 참조하세요.

변경 사항 배열에서 핑을 통해 여러 변경 사항을 수신할 수 있습니다.

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 업데이트 수신에서 설명한 바와 같이 서버가 HTTP GET 요청으로 응답해야 합니다.

콜백 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를 지정할 필요가 없습니다.

인증에 성공하면 이벤트 실행 시 실시간 핑이 발생하고 최대 몇 분 정도의 지연이 있을 수 있습니다. 실시간 통합 문제 해결을 참조하세요.