顧客檔案自訂廣告受眾

行銷 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 呼叫執行 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 像素的資料來建立廣告受眾。

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

• 類似廣告受眾：識別您已經認識的用戶，並在 Facebook 應用程式上向類似的用戶投遞廣告。

• 離線自訂廣告受眾：根據瀏覽過您的商店、致電過顧客服務或經由其他離線方式採取過行動的用戶來建立廣告受眾。

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

另請參閱

• 自訂廣告受眾
• 自訂廣告受眾用戶
• 自訂廣告受眾連線階段
• 自訂廣告受眾的服務條款