客户文件自定义受众

您可以使用我们的市场营销 API，根据客户信息构建目标自定义受众。这些信息包括邮箱、手机号、姓名、出生日期、性别、地点、应用用户编号、公共主页范围用户编号、Apple 的广告 ID (IDFA) 或 Android 广告编号。

您可向受众中添加数量不限的记录，但每次最多只可加入 10,000 个。对自定义受众的更改不会立即生效，通常需要多达 24 小时。您请求移除的记录的数量和/或您帐户内包含的自定义受众的数量都将增加处理此请求所需的时间。

为改进广告主创建和管理受众的方式，我们会标记在 2 年以上的时间里未在任何投放中的广告组中使用的客户文件自定义受众，以陆续删除。您需要在我们采取措施前提供指示说明。如果受众已移至“过期受众”阶段并被标记，您将需要提供指示说明。如果您在投放中的广告组中使用标记受众，我们会将其视作保留受众的指示；如果您决定不在投放中的广告组中使用标记受众，我们会将其视作删除受众的指示。如需了解更多信息，请查看自定义受众概述文件。

构建自定义受众

第 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/v19.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 作哈希处理，但必须对所有个人身份识别信息（例如邮箱和姓名）作哈希处理。如需了解相关详情，请参阅对数据作哈希和标准化处理。

您可为一个记录提供部分或所有多键。如需了解相关详情，请参阅多键外部编号匹配。

使用多键匹配结果添加用户

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 键，则还必须添加公共主页编号清单。您只能向我们发送一个 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 对数据进行哈希处理；我们不支持其他哈希机制。除外部标识符、应用用户编号、公共主页范围内的用户编号和移动广告客户编号以外，对所有其他数据均必须执行此操作。

请先将数据标准化，然后再对其作哈希处理，以便我们处理数据。只有名字 (FN) 和姓氏 (LN) 支持特殊字符和非罗马字母。如要获得最佳匹配结果，请提供不含任何特殊字符的罗马字母翻译。

哈希处理

请为标准化的键提供 SHA256 值，并提供该值的 HEX 表示（使用小写 A 至 F）。PHP 的哈希功能将转换标准化的邮箱和手机号。

外部标识符

您可使用自己的标识符（即外部标识符或 EXTERN_ID）为受众匹配用户。此标识符可以是广告主提供的任何唯一编号，如会员编号、用户编号和外部 Cookie 编号。

为更好地进行匹配，您还应在发送编号时使用完全相同的格式。例如，如果您选择使用 SHA256 对数据进行哈希处理，请确保以后继续使用相同的哈希值。

您可以将这些编号用作各个键，以将用户从自定义受众中删除，或新建自定义受众。如此一来，您就无需重新上传任何其他匹配键。如果您使用经过哈希处理的个人信息和 EXTERN_ID 标记某位用户，则当我们将该用户与 Facebook 上的用户进行匹配时，我们会给予 EXTERN_ID 较低的优先级。

在单个广告帐户内，您可以重复使用 EXTERN_ID 映射构建自定义文件自定义受众。

如果您广告帐户的受众已有 EXTERN_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

替换用户 API

借助 /<CUSTOM_AUDIENCE_ID>/usersreplace 端点，您可以使用一个 API 调用执行以下 2 个操作：

• 从特定受众中完全移除现有用户
• 用一组新用户替换这些用户。

通过 /<CUSTOM_AUDIENCE_ID>/usersreplace 端点，您可以自动删除所有现有用户，而不必上传想要删除的用户名单。如果受众是投放中广告组的一部分，此端点不会重置您广告组的机器学习阶段，这与 /<CUSTOM_AUDIENCE_ID>/users 端点的 POST 或 DELETE API 调用不同。

替换用户 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 端点的添加操作上传其余部分。

• 受众创建完成后，请向 /<CUSTOM_AUDIENCE_ID>/usersreplace 发出 POST 调用，以指定要添加到自定义受众的用户名单。

  • 替换流程开始后，系统会将您受众的 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 请求后，您将获得具有以下字段的响应：

替换 API 常见错误

从替换端点返回的所有错误都含有错误代码 2650。以下是返回的一些最常见错误子代码及其解决方案指南。

资源

您可构建、定位或分享的其他受众类型如下所示：

• 来自您网站的自定义受众 — 根据浏览特定页面或在您网站上执行操作的用户创建受众。根据您网站上 Meta Pixel 像素代码的数据构建受众。

• 您移动应用的自定义受众 — 根据使用您移动应用的用户创建受众。根据来自应用事件的数据构建受众。

• 类似受众 — 识别您已知晓的用户，并向类似的 Facebook 应用用户展示广告。

• 线下自定义受众 — 根据曾光顾过门店、致电客服，或通过其他线下途径做出操作的用户创建受众。

• 全屏广告互动受众 — 创建包含与您的全屏广告互动的任何用户的受众。

另请参阅

• 自定义受众
• 自定义受众用户
• 自定义受众会话
• 自定义受众服务条款