顧客檔案自訂廣告受眾

您可以使用我們的營銷 API，根據顧客資訊建立自訂目標廣告受眾。這些資訊包括電郵地址、手機號碼、姓名、出生日期、性別、地點、應用程式用戶編號、專頁範圍用戶編號、Apple 廣告識別碼（IDFA）或 Android 廣告編號。

您可將無限個記錄加入廣告受眾中，但每次最多只可加入 10,000 個。為自訂廣告受眾作出的變更不會立即生效，一般需要等待最多 24 小時。您要求移除的記錄數量及／或您帳戶所包含的自訂廣告受眾數量，均會增加系統處理此要求所需的時間。

為幫助廣告客戶建立和管理其廣告受眾，顧客檔案自訂廣告受眾如在兩年以上（滾動式計算）未在任何刊登中的廣告組合內使用，便會被標示為刪除。您需要在我們採取行動前提供指示說明。廣告受眾一經移動至「過期分享對象」狀態並被標示，您將需要提供指示說明，也就是在刊登中的廣告組合中使用或不使用被標示的廣告受眾。如果使用，我們將認為這是保留廣告受眾的指示；如果決定不使用，我們將認為這是刪除廣告受眾的指示。如要了解更多資訊，請查看自訂廣告受眾概覽文件。

建立自訂廣告受眾

第 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 作雜湊處理，但您必須雜湊處理所有個人識別資料，例如電郵和姓名。詳情請查看對資料作雜湊和標準化處理。

您可為一個記錄提供部分或所有多重鍵。詳情請查看多重鍵外部編號配對。

使用多重鍵配對結果新增用戶

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 呼叫來執行兩項動作：

• 從特定廣告受眾中完全移除現有用戶
• 將這些用戶替換為一組新用戶。

透過 /<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>/users 新增或移除用戶，限制時段為透過 /<CUSTOM_AUDIENCE_ID>/usersreplace 執行替換操作期間。若您嘗試在第一項替換操作完成前開始另一項替換操作，便會收到表示替換操作已在進行中的訊息。

• 每個替換階段的最長持續時間為 90 分鐘。工作階段開始起計 90 分鐘後，API 會拒絕任何傳送至該階段的批次。若傳送批次的時間需要多於 90 分鐘，我們建議先等待該工作階段的替換操作完結，然後使用 /<CUSTOM_AUDIENCE>/users 端點的新增操作上載剩餘的批次。

• 廣告受眾準備就緒後，請向 /<CUSTOM_AUDIENCE_ID>/usersreplace 發出 POST 呼叫，指定要以自訂廣告受眾進行替換的用戶名單。

  • 替換程序開始後，廣告受眾的 replace_in_progress 將會切換為 operation_status。
  • 如果替換操作失敗，廣告受眾的 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 常見錯誤

從 Replace 端點返回的所有錯誤均包含錯誤代碼 2650。以下是一些最常見的返回錯誤子代碼，以及解決這些錯誤的指引。

相關資源

您可組建、鎖定或分享的其他廣告受眾類型如下所示：

• 來自您網站的自訂廣告受眾 — 根據瀏覽過特定頁面，或在您網站上執行過操作的用戶建立廣告受眾。根據來自您網站上 Meta 像素的資料建立廣告受眾。

• 來自流動應用程式的自訂廣告受眾 — 根據使用您流動應用程式的用戶建立廣告受眾。根據來自應用程式事件的資料建立廣告受眾。

• 類似廣告受眾 — 識別您已知的用戶，並向類似的 Facebook 用戶展示廣告。

• 離線自訂廣告受眾 — 根據曾光顧過門店、致電客戶服務，或透過其他離線途徑採取動作的用戶建立廣告受眾。

• 全螢幕互動廣告受眾 — 建立包含與您全螢幕廣告互動的任何用戶的廣告受眾。

另請參閱

• 自訂廣告受眾
• 自訂廣告受眾用戶
• 自訂廣告受眾工作階段
• 自訂廣告受眾服務條款