고객 파일 맞춤 타겟

마케팅 API를 사용하면 고객 정보를 활용해 맞춤 타겟을 빌드할 수 있습니다. 여기에는 이메일 주소, 전화번호, 이름, 생년월일, 성별, 위치, 앱 사용자 ID, 페이지 범위 사용자 ID, Apple 광고 ID(IDFA) 또는 Android 광고 ID가 포함됩니다.

타겟에 기록을 무제한으로 추가할 수 있지만 한 번에 추가할 수 있는 최대 수는 10,000개입니다. 맞춤 타겟의 변경 사항은 즉시 적용되지 않으며 일반적으로 최대 24시간 소요됩니다. 삭제를 요청한 기록 수 및/또는 계정에 보유한 맞춤 타겟 수에 따라 이 요청을 처리하는 데 걸리는 시간이 늘어납니다.

광고주가 타겟을 생성하고 관리하는 방법을 개선하기 위해 2년 넘게 활성화된 광고 세트에서 사용되지 않은 고객 파일 맞춤 타겟은 삭제 플래그가 수시로 표시됩니다. Facebook에서 조치를 취하기 전에 지침을 제공해야 합니다. 타겟이 '만료 타겟' 단계로 이동하여 플래그가 표시되면 활성화된 광고 세트에서 플래그된 타겟을 사용할지(타겟을 유지하라는 지침으로 간주), 활성화된 광고 세트에서 플래그된 타겟을 사용하지 않을지(타겟을 삭제하라는 지침으로 간주) 결정하여 Facebook에 지침을 제공해야 합니다. 자세한 내용은 맞춤 타겟 개요 문서를 참조하세요.

맞춤 타겟 빌드하기

1단계: 빈 맞춤 타겟 만들기

API 호출에서 subtype=CUSTOM과 customer_file_source를 지정합니다.

curl -X POST \
  -F 'name="My new Custom Audience"' \
  -F 'subtype="CUSTOM"' \
  -F 'description="People who purchased on my website"' \
  -F 'customer_file_source="USER_PROVIDED_ONLY"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_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 = {
  'name' : 'My new Custom Audience',
  'subtype' : 'CUSTOM',
  'description' : 'People who purchased on my website',
  'customer_file_source' : 'USER_PROVIDED_ONLY',
};
const customaudiences = (new AdAccount(id)).createCustomAudience(
  fields,
  params
);
logApiCallResult('customaudiences api call complete.', customaudiences);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\CustomAudience;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

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

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

$fields = array(
);
$params = array(
  'name' => 'My new Custom Audience',
  'subtype' => 'CUSTOM',
  'description' => 'People who purchased on my website',
  'customer_file_source' => 'USER_PROVIDED_ONLY',
);
echo json_encode((new AdAccount($id))->createCustomAudience(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

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

fields = [
]
params = {
  'name': 'My new Custom Audience',
  'subtype': 'CUSTOM',
  'description': 'People who purchased on my website',
  'customer_file_source': 'USER_PROVIDED_ONLY',
}
print AdAccount(id).create_custom_audience(
  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 = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createCustomAudience()
      .setName(\"My new Custom Audience\")
      .setSubtype(CustomAudience.EnumSubtype.VALUE_CUSTOM)
      .setDescription(\"People who purchased on my website\")
      .setCustomerFileSource(CustomAudience.EnumCustomerFileSource.VALUE_USER_PROVIDED_ONLY)
      .execute();

  }
}

require 'facebook_ads'

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

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

ad_account = FacebookAds::AdAccount.get(id)
customaudiences = ad_account.customaudiences.create({
    name: 'My new Custom Audience',
    subtype: 'CUSTOM',
    description: 'People who purchased on my website',
    customer_file_source: 'USER_PROVIDED_ONLY',
})

매개변수

2단계: 사용자 리스트 지정

/{audience_id}/users 엔드포인트에 대한 POST API 호출을 사용하여 맞춤 타겟에 추가하고자 하는 사용자 리스트를 지정합니다.

매개변수

{
  "session_id":9778993, 
  "batch_seq":10, 
  "last_batch_flag":true, 
  "estimated_num_total":99996 
} 

{ 
  "schema":"EMAIL_SHA256", 
  "data":
    [
      ["<HASHED_DATA>"], 
      ["<HASHED_DATA>"], 
      ["<HASHED_DATA>"] 
    ]
}

미국 사용자의 데이터 처리 옵션

{
   "payload": {
       "schema": [
           "EMAIL",
                    "DATA_PROCESSING_OPTIONS"
       ],
       "data": [
           [
               "<HASHED_DATA>
",
                           []
           ]
       ]
   }
}

{
   "payload": {
       "schema": [
           "EMAIL",
                    "DATA_PROCESSING_OPTIONS"
       ],
       "data": [
           [
               "<HASHED_DATA>
",
                           ["LDU"]
           ]
       ]
   }
}

{
    "customer_consent": true,
    "payload": {
        "schema": [
            "EMAIL",
            "DATA_PROCESSING_OPTIONS",
            "DATA_PROCESSING_OPTIONS_COUNTRY",
            "DATA_PROCESSING_OPTIONS_STATE"
        ],
        "data": [
            [
                "<HASHED_DATA>",
                ["LDU"],
                1,
                1000
            ]
        ]
    }
}

session 필드

응답

성공한 경우 응답에 다음 필드를 포함한 JSON 개체가 포함됩니다.

맞춤 타겟을 비즈니스 개체와 공유에 대해 자세히 알아보세요.

타겟 멤버 삭제

/{audience_id}/users 엔드포인트에 대한 DELETE API 호출을 사용하여 맞춤 타겟에서 삭제할 사용자 리스트를 지정합니다.

curl -X DELETE \
  --data-urlencode 'payload={ 
    "schema": "EMAIL_SHA256", 
    "data": [ 
      "<HASHED_DATA>", 
      "<HASHED_DATA>", 
      "<HASHED_DATA>" 
    ] 
  }' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

또는 method 매개변수를 추가하고 타겟 멤버를 추가하는 데 사용한 POST 요청에서 DELETE로 설정할 수 있습니다.

EXTERN_ID를 사용하여 리스트에서 사용자를 삭제할 수도 있습니다(가능한 경우).

curl -X DELETE \
  --data-urlencode 'payload={ 
    "schema": "EXTERN_ID", 
    "data": [ 
      "<ID>", 
      "<ID>", 
      "<ID>" 
    ] 
  }' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

이 엔드포인트를 사용하여 광고 계정 전체에 걸쳐 모든 맞춤 타겟에서 사용자 리스트를 삭제할 수 있습니다.

이 정보가 처리되지 않은 이유가 몇 가지 있을 수 있습니다. 예를 들어 비즈니스 포트폴리오에서 광고 계정을 소유하고 있지 않은 경우 아직 맞춤 타겟 약관을 수락하지 않았거나 정보가 사용자와 일치하지 않습니다.

계정 센터 계정을 삭제하려면 사용자 업데이트에서와 같은 필드를 포함하고 다음으로 HTTP DELETE를 호출합니다.

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/usersofanyaudience

멀티 키 매칭

기록의 일치율을 높이려면 개별 키로 구성된 배열 형태로 여러 키를 제공합니다(예: [EXTERN_ID, LN, FN, EMAIL]). EXTERN_ID를 해시할 필요는 없지만 이메일, 이름과 같은 모든 개인 식별 정보를 해시해야 합니다. 자세한 내용은 데이터 해싱 및 정규화를 참조하세요.

기록에 멀티 키의 일부 또는 전체를 제공할 수 있습니다. 자세한 내용은 멀티 키 외부 ID 매칭을 참조하세요.

멀티 키 매칭을 사용하여 사용자 추가

curl \
  -F 'payload={ 
    "schema": [ 
      "FN", 
      "LN", 
      "EMAIL" 
    ], 
    "data": [ 
      [ 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ], 
      [ 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ] 
    ] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

PAGEUID 사용

PAGEUID 키를 사용하면 페이지 ID 리스트도 포함해야 합니다. Facebook에 하나의 PAGEUID만 보낼 수 있으며, 이는 하나의 요소를 포함한 배열이어야 합니다.

curl -X POST \
  -F 'payload={
       "schema": [
         "PAGEUID"
       ],
       "is_raw": "true",
       "page_ids": [
            "<PAGE_IDs>"
            ],
       "data": [
         [
           "<HASH>",
           "<ID>",
           "<ID>",
           "<VALUE>"
         ],
         [
           "<HASH>",
           "<ID>",
           "<ID>",
           "<VALUE>"
         ],
         [
           "<HASH>",
           "<ID>",
           "<ID>",
           "<VALUE>"
         ]
       ]
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

멀티 키의 해싱 및 정규화

SHA256로 데이터를 해시해야 합니다. 다른 해싱 메커니즘은 지원하지 않습니다. 이는 외부 ID, 앱 사용자 ID, 페이지 범위 사용자 ID 및 모바일 광고주 ID를 제외한 모든 데이터에 필수입니다.

데이터를 해시하기 전에 처리 가능하도록 정규화합니다. 이름(FN)과 성(LN)만 특수 문자와 비로마자를 지원합니다. 최적의 매칭 결과를 얻으려면 특수 문자를 포함하지 않는 로마자 번역을 제공하세요.

해시

A~F의 소문자를 사용하여 정규화된 키의 SHA256 값과 이 값의 HEX 표시를 지정합니다. PHP의 해시 함수를 통해 정규화된 이메일과 전화번호를 전환할 수 있습니다.

외부 ID

외부 ID(EXTERN_ID)라고 하는 고유한 ID가 있는 타겟과 사용자를 매칭할 수 있습니다. 광고주의 모든 고유한 ID(예: 로열티 멤버십 ID, 사용자 ID, 외부 쿠키 ID)가 될 수 있습니다.

매칭 결과를 개선하려면 ID를 보낼 때와 정확히 똑같은 형식을 사용해야 합니다. 예를 들어 SHA256을 사용하여 해시하기로 했다면 이와 동일한 해시 값을 사용해야 합니다.

이러한 ID를 개별 키로 사용하여 맞춤 타겟에서 사용자를 삭제하거나 맞춤 타겟을 새로 만들 수 있습니다. 이렇게 하면 다른 매칭 키를 다시 업로드하지 않아도 됩니다. 해시된 개인 정보와 EXTERN_ID로 누군가를 태그하면 Facebook 사용자와 매칭할 때 EXTERN_ID 우선순위가 낮게 설정됩니다.

단일 광고 계정에서 고객 파일 맞춤 타겟 전체에 EXTERN_ID 매핑을 다시 사용할 수 있습니다.

광고 계정에 EXTERN_ID 필드를 포함한 타겟이 있는 경우 해당 ID만 사용하여 신규 가입 타겟을 만드세요.

curl \
  -F 'payload={"schema":"EXTERN_ID","data":["<ID>","<ID>"]}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

EXTERN_ID로 태그된 사람도 멀티 키 매칭으로 추가할 수 있습니다.

curl \
  -F 'payload={ 
    "schema": [ 
      "EXTERN_ID", 
      "FN", 
      "EMAIL", 
      "LN" 
    ], 
    "data": [ 
      [ 
        "<ID>", 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ], 
      [ 
        "<ID>", 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ], 
      [ 
        "<ID>", 
        "<HASH>", 
        "<HASH>", 
        "<HASH>" 
      ] 
    ] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/<CUSTOM_AUDIENCE_ID>/users

Replace Users API

/<CUSTOM_AUDIENCE_ID>/usersreplace 엔드포인트를 사용하면 하나의 API 호출로 두 가지 작업을 수행할 수 있습니다.

• 특정 타겟으로부터 기존 사용자를 완전히 삭제합니다.
• 이 사용자는 새로운 사용자 세트로 교체합니다.

/<CUSTOM_AUDIENCE_ID>/usersreplace 엔드포인트를 사용하면 삭제하려는 사용자 리스트를 업로드하지 않고 모든 기존 사용자를 자동으로 삭제할 수 있습니다. 이 엔드포인트는 타겟이 활성 광고 세트에 포함되었을 때 광고 세트의 머신 러닝 단계를 재설정하지 않습니다. 이는 /<CUSTOM_AUDIENCE_ID>/users 엔드포인트에 대한 POST 또는 DELETE API 호출과는 다릅니다.

Replace Users API는 다음과 같은 요구 사항을 충족하는 타겟에만 적용됩니다.

• 교체 프로세스를 실행하기 전의 사용자 수는 1억 명 이내여야 합니다. 타겟이 1억 명보다 많으면 /<CUSTOM_AUDIENCE_ID>/users 엔드포인트를 사용하여 사용자를 추가하거나 삭제하는 것이 좋습니다.
• 하위 유형은 CUSTOM으로 설정해야 합니다.
• 가치 기반 고객 파일 맞춤 타겟을 가치 기반이 아닌 고객 파일 맞춤 타겟으로 바꾸거나 그 반대로 바꿀 수 없습니다.

시작하기

교체 프로세스를 시작하기 전에 다음을 수행하는 것이 좋습니다.

• 타겟의 operation_status는 Normal인지 확인합니다.

• /<CUSTOM_AUDIENCE_ID>/usersreplace를 통해 교체 작업을 진행하는 도중에는 /<CUSTOM_AUDIENCE_ID>/users를 통해 사용자를 추가하거나 삭제할 수 없습니다. 첫 번째 교체 작업이 완료되기 전에 두 번째 교체 작업을 시도하면 교체 작업이 이미 진행 중이라는 메시지를 받게 됩니다.

• 교체 세션 1개의 최대 시간은 90분입니다. API는 세션이 시작되고 나서 90분이 지난 후 수신되는 세션에 대한 배치를 거부합니다. 90분 이상 배치를 전송해야 할 경우 해당 세션의 교체 작업이 완료되기를 기다렸다가 /<CUSTOM_AUDIENCE>/users 엔드포인트의 추가 작업으로 나머지 업로드를 실행합니다.

• 타겟이 준비되면 POST 호출을 /<CUSTOM_AUDIENCE_ID>/usersreplace로 보내서 맞춤 타겟으로 교체할 사용자 리스트를 지정합니다.

  • 교체 작업을 시작하면 타겟의 operation_status가 replace_in_progress로 전환됩니다.
  • 교체 작업이 완료되지 않으면 타겟의 operation_status가 replace_error로 전환됩니다.

호출 매개변수

/<CUSTOM_AUDIENCE_ID>/usersreplace로 보내는 POST 호출에 다음과 같은 매개변수를 포함할 수 있습니다.

{
  'session_id':9778993, 
  'batch_seq':10, 
  'last_batch_flag':true, 
  'estimated_num_total':99996 
}

{ 
  "schema":"EMAIL", 
  "data":["<HASHED_EMAIL>", "<HASHED_EMAIL>", "<HASHED_EMAIL>" ]
}

세션 필드

페이로드 필드

POST 요청을 보내면 다음의 필드가 포함된 응답을 받습니다.

Replace API의 일반적 오류

교체 엔드포인트에서 반환된 모든 오류는 오류 코드가 2650입니다. 반환되는 가장 일반적인 오류 하위 코드와 해결 방법에 대한 지침은 다음과 같습니다.

리소스

빌드, 타게팅 또는 공유가 가능한 기타 타겟 유형이 또 있습니다.

• 웹사이트 기반 맞춤 타겟 — 특정 페이지를 방문했거나 웹사이트에서 행동을 보인 사람을 기반으로 타겟을 만듭니다. 사이트에서 Meta 픽셀의 데이터를 기반으로 타겟을 빌드합니다.

• 모바일 앱 기반 맞춤 타겟 — 모바일 앱 사용자를 기반으로 타겟을 만듭니다. 앱 이벤트의 데이터를 기반으로 타겟을 빌드합니다.

• 유사 타겟 — 이미 알고 있는 사람을 파악하고 Facebook 앱의 유사한 사용자에게 광고합니다.

• 오프라인 맞춤 타겟 — 매장을 방문했거나 고객 서비스에 전화를 걸었거나, 기타 오프라인 방식으로 행동을 취한 사람을 기반으로 타겟을 만듭니다.

• 캔버스 참여 타겟 — 캔버스에 참여한 사람을 포함하는 타겟을 만듭니다.

기타 참고 자료

• 맞춤 타겟
• 맞춤 타겟 사용자
• 맞춤 타겟 세션
• 맞춤 타겟 서비스 약관