마케팅 API

잠재 고객 검색

Webhooks 또는 대량 읽기로 잠재 고객을 읽을 수 있습니다.

시작하기 전에

ad_id, campaign_id와 같은 광고별 필드를 읽으려면 다음 항목이 필요합니다.

모든 잠재 고객 데이터 및 광고 수준 데이터를 읽으려면 다음 항목이 필요합니다.

참고: 이 페이지 관리자가 잠재 고객을 직접 지정하거나 잠재 고객 액세스 관리자에 액세스 권한을 부여한 적이 없는 경우 모든 페이지 관리자에게 잠재 고객 액세스 권한이 있습니다. 비즈니스 운영자가 잠재 고객 액세스 권한을 직접 설정하는 경우, 이는 페이지의 기본 관리자에게 잠재 고객 액세스 권한이 있는지 여부와 관계없이 비즈니스 운영자의 구성에 좌우됩니다.

사용 제한

사용 제한은 Facebook 페이지에 대해 지난 90일 동안 발생한 잠재 고객 수의 24x200배입니다. 24시간 이내에 이보다 더 많은 수의 호출을 보낼 경우 해당 요청은 오류를 반환합니다.

기간 기준 필터링

GET 요청을 /ads/lead_gen/export_csv/ 엔드포인트로 보내세요. 이 경우 데이터 형식은 POSIX 또는 UNIX 타임스탬프입니다.

curl -i -X GET "https://www.facebook.com/ads/lead_gen/export_csv/
    ?id=<FORM_ID>
    &type=form
    &from_date=1482698431
    &to_date=1482784831"

주의 사항

  • from_date가 설정되지 않았거나 양식 생성 시간보다 작은 경우 양식 생성 시간이 사용됩니다.

  • to_date가 설정되지 않았거나 현재 시간보다 미래인 경우 현재 시간이 사용됩니다.

  • TSV에 광고 ID 또는 광고 그룹 ID가 없는 항목이 있는 경우 다음과 같은 이유 때문일 수 있습니다.

    • 잠재 고객이 일반 도달에서 생성됩니다. 이 경우 TSV의 is_organic이 1로 표시됩니다. 그렇지 않은 경우 이 값은 0입니다.
    • 잠재 고객이 광고 미리 보기에서 제출될 수 있습니다.
    • 잠재 고객을 요청하는 사용자는 광고 계정에 대한 광고주 권한이 없습니다.

Webhooks

잠재 고객용 광고의 실시간 업데이트를 받습니다.

1단계: 시작하기

Webhooks 시작하기 가이드를 참조하여 엔드포인트를 설정하고 Webhooks를 구성합니다.

2단계: 장기 실행 페이지 액세스 토큰 가져오기

만료 걱정 없이 데이터를 지속적으로 가져오려면 단일 장기 실행 페이지 토큰을 생성합니다.

3단계: 페이지에 앱 설치하기

페이지용 Webhooks 가이드를 참조하여 페이지에 앱을 설치하는 방법을 알아봅니다.

Webhooks 응답

잠재 고객 확보를 생성하면 앱에서 다음과 같은 Webhooks 응답을 받습니다.

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/v21.0/{lead-id}/
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<LEAD_ID>';
const api = bizSdk.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 = {
};
const sample_code = (new Lead(id)).get(
  fields,
  params
);
logApiCallResult('sample_code api call complete.', sample_code);
Open In Graph API Explorer
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 = '<LEAD_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
)->exportAllData(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<LEAD_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
}
print Lead(id).get(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
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 = \"<LEAD_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Lead(id, context).get()
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<LEAD_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

lead = FacebookAds::Lead.get(id ,'')
Open In Graph API Explorer

성공할 경우 앱은 다음과 같은 응답을 받습니다.

{
  "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"
    ]
  }],
  ...
}

더 알아보기

  • 많은 CRM이 잠재 고객용 광고 데이터를 CRM으로 마이그레이션하는 실시간 업데이트를 제공합니다. 이용 가능한 CRM 통합을 참조하세요.
  • 실시간 업데이트의 핑은 다음과 같이 구성됩니다. 자세한 정보는 실시간 업데이트, 블로그를 참조하세요.
  • 인증에 성공하면 이벤트 실행 시 실시간 핑이 발생하고 최대 몇 분 정도의 지연이 있을 수 있습니다. 실시간 통합 문제 해결을 참조하세요.

Github 저장소에서 이 구현의 예시를 확인할 수 있습니다.

일괄 읽기

2018년 7월 2일 이후에 만든 앱은 잠재 고객을 읽을 때 leads_retrieval 권한을 사용하도록 강제 적용됩니다.

leads는 광고 그룹과 양식 노드에 모두 존재합니다. 이는 각 개체와 관련된 모든 데이터를 반환합니다. 양식은 여러 광고에서 다시 사용할 수 있으므로 양식에는 양식을 사용하는 광고보다 훨씬 더 많은 잠재 고객이 포함될 수 있습니다.

광고 기준 일괄 읽기:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{adgroup-id}/leads
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_GROUP_ID>';
const api = bizSdk.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 = {
};
const leadss = (new Ad(id)).getLeads(
  fields,
  params
);
logApiCallResult('leadss api call complete.', leadss);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_GROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
);
echo json_encode((new Ad($id))->getLeads(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
}
print Ad(id).get_leads(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
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 = \"<AD_GROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).getLeads()
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
leadss = ad.leads({
    fields: {  },
})
Open In Graph API Explorer

양식 기준 읽기:

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 -X GET \
"https://graph.facebook.com/<API_VERSION>/<LEADGEN_ID>?
fields=custom_disclaimer_responses"

응답:

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

잠재 고객 필터링

이 예에서는 타임스탬프에 따라 잠재 고객을 필터링합니다. 타임스탬프는 Unix 타임스탬프여야 합니다.

curl -X GET \
  -d 'filtering=[
       {
         "field": "time_created",
         "operator": "GREATER_THAN",
         "value": 1729974189
       }
     ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{adgroup-id}/leads
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_GROUP_ID>';
const api = bizSdk.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 = {
  'filtering' : [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
};
const leadss = (new Ad(id)).getLeads(
  fields,
  params
);
logApiCallResult('leadss api call complete.', leadss);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_GROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'filtering' => array(array('field' => 'time_created','operator' => 'GREATER_THAN','value' => 1721709809)),
);
echo json_encode((new Ad($id))->getLeads(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'filtering': [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
}
print Ad(id).get_leads(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
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 = \"<AD_GROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).getLeads()
      .setParam(\"filtering\", \"[{\\"field\\":\\"time_created\\",\\"operator\\":\\"GREATER_THAN\\",\\"value\\":1721709809}]\")
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
leadss = ad.leads({
    fields: {  },
    filtering: [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
})
Open In Graph API Explorer

operator는 다음 값 중 하나를 갖습니다.

연산자의미

LESS_THAN

타임스탬프보다 작은 값을 필터링합니다.

GREATER_THAN

타임스탬프보다 큰 값을 필터링합니다.

GREATER_THAN_OR_EQUAL

타임스탬프보다 크거나 같은 값을 필터링합니다.

토큰화

양식에 맞춤 설정 필드 ID가 있을 경우 반환된 필드와 값은 지정된 필드와 값이 됩니다.

리소스