行銷 API

顧客檔案自訂廣告受眾

行銷 API 可讓您從顧客資訊建立目標自訂廣告受眾。這些資訊包括電子郵件地址、電話號碼、姓名、出生日期、性別、地點、應用程式用戶編號、粉絲專頁範圍用戶編號、Apple 的廣告識別碼（IDFA），或 Android 廣告編號。

您是企業資料的擁有者，必須負責建立及管理此資料。這包括顧客關係管理（CRM）系統的資訊。若要建立廣告受眾，您必須分享您的雜湊格式資料，以維護隱私。請參閱資料的雜湊處理與正規化。Meta 會將此資料與我們的雜湊資料比較，以決定是否將 Facebook 上的某些用戶加入您的廣告受眾。

您可將不限數量的記錄加入廣告受眾，但一次最多 10,000 筆。自訂廣告受眾的變更不會立即生效，通常需要長達 24 小時。您要求移除的記錄數量和／或您帳號包含的自訂廣告受眾數量將增加處理此要求所花費的時間。

為了改進廣告商建立和管理廣告受眾的方式，若顧客檔案自訂廣告受眾在任何有效的廣告組合中未使用的時間超過兩年，系統將以先到先審的方式將其標幟為刪除。在我們採取任何動作之前，您必須向我們提供您的指示。一旦系統將廣告受眾移至「即將到期的廣告受眾」階段並加以標幟，您將必須透過以下方法來提供您的指示：在有效的廣告組合中使用已標幟的廣告受眾，我們會將其視為保留廣告受眾的指示；或決定不在有效的廣告組合中使用已標幟的廣告受眾，我們會將其視為刪除廣告受眾的指示。如需更多資訊，請參閱自訂廣告受眾總覽文件。

如果您使用轉換 API 分享轉換事件，則可以建立自訂廣告受眾網站，無須上傳其他資料。但您可以繼續上傳支援的客戶資訊，以建立客戶檔案自訂廣告受眾。

使用我們新的替換 API 可以完全移除廣告受眾的現有用戶，並將其替換為一組新的用戶。使用替換 API 進行廣告受眾更新，不會將廣告組合移回系統學習階段。

建立自訂廣告受眾

步驟 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',
})

參數

名稱說明

customer_file_source
列舉字串

說明自訂廣告受眾中的顧客資訊一開始的收集方式。
值：

  • USER_PROVIDED_ONLY
    廣告商直接向顧客收集資訊
  • PARTNER_PROVIDED_ONLY
    廣告商直接向合作夥伴（例如，代理商或資料供應商）收集資訊
  • BOTH_USER_AND_PARTNER_PROVIDED
    廣告商直接向顧客收集資訊，也向合作夥伴（例如，代理商）收集資訊

name
字串

自訂廣告受眾名稱

description
字串

自訂廣告受眾說明

subtype
字串

自訂廣告受眾的類型

步驟 2：指定用戶名單

對 /{audience_id}/users 端點使用 POST API 呼叫，以指定您要加入自訂廣告受眾的用戶名單。

參數

名稱說明

session
JSON 物件

必要項目
使用 session 參數追蹤是否已上傳特定批次的用戶。
若要上傳超過 10,000 名用戶，您需要將其分成多個批次，每次要求最多可包含 10,000 名用戶。


範例

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

payload
JSON 物件

必要項目
包括 schema 和 data。

範例

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

適用於美國用戶的資料處理選項

如果您想要在 2023 年 6 月 1 日當日／之後透過顧客名單自訂廣告受眾，針對加州用戶啟用「限制資料使用」，您必須上傳新的廣告受眾，或更新帶有「限制資料使用」標示的現有廣告受眾。視需求定期更新及維護廣告受眾及用戶的「限制資料使用」狀態。

請注意：適用於一群廣告受眾用戶的「限制資料使用」標示，不會自動套用至不同的廣告受眾。廣告主必須透過他們選擇的條件，以相同的方式分別管理每群現有顧客清單自訂廣告受眾。「限制資料使用」標示必須分別套用至廣告主的廣告鎖定的各群廣告受眾。

若記錄明確「不」啟用LDU，您可以傳送空白的data_processing_options陣列或移除承載內的欄位。空白陣列範例：

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

若要明確啟用LDU 並由 Meta 指定地理位置（方法為不包括指定記錄的州 / 省及國家 / 地區），請為各記錄指定包含 LDU 的陣列：

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

若要啟用 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 欄位

名稱說明

session_id
64 位元正整數

必要項目
用於追蹤連線階段的識別碼。此編號必須由廣告主產生，且為特定廣告帳號中不重複的編號。

batch_seq
正整數

必要項目
用於識別目前連線階段中所列要求的編號。此編號必須是從 1 開始的序列編號。

last_batch_flag
布林值

必要項目

向我們的系統指示進行中之「替換」連線階段的所有批次皆已提供。設為 true 時，目前的要求為目前連線階段中的最後一個，該連線階段不再接受任何其他批次。如果您沒有傳送此標示，我們會在收到第一個批次後 90 分鐘自動終止連線階段。在 90 分鐘後收到的任何批次也會被捨棄。您必須標記最後一個要求，讓 Meta 知道其為最後一個批次。

estimated_num_total
整數

選用項目
要在此連線階段中上傳的預估用戶總數。此欄位可用於改善此連線階段的處理效率。

回應

成功的回應包含 JSON 物件及下列欄位：

名稱說明

audience_id
數值字串

廣告受眾識別碼

session_id
整數

您傳入的連線階段編號

num_received
整數

這個連線階段目前為止收到的用戶總人數

num_invalid_entries
整數

以不正確的雜湊傳送的項目數。這些項目未傳回符合項目，也未新增至自訂廣告受眾。這不是確切數字，而是代表不符合的用戶數範圍。

invalid_entry_samples
字串或對應的 JSON 陣列 {string: string}

在目前要求中找到的最多 100 個無效項目範例

深入瞭解將自訂廣告受眾與企業物件分享。

移除廣告受眾成員

對 /{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）支援特殊字元和非羅馬字母。為了獲得最佳的配對結果，請提供不含特殊字元的羅馬字母翻譯。

請下載此 CSV 檔案

以取得以下參數的正確正規化和雜湊資料的範例。



下載（點擊右鍵 > 另存連結）
金鑰準則

EMAIL
條件：電子郵件地址

需雜湊處理
修剪頭尾的空格，並將所有字元轉換為小寫。

PHONE
條件：電話號碼

需雜湊處理
移除符號、字母和任何開頭的零。如果未指定 COUNTRY 欄位，應在前方加上國碼／區碼。

GEN
條件：性別

需雜湊處理
使用下列值：m 代表男性，f 代表女性。

DOBY
條件：生日年份

需雜湊處理
使用 YYYY 格式：1900 至當前年份。

DOBM
條件：生日月份

需雜湊處理
使用 MM 格式：01 至 12。

DOBD
條件：生日

需雜湊處理
使用 DD 格式：01 至 31。

LN 和 FN
條件：姓名

需雜湊處理
只能使用 a-z。僅限小寫字母，不可包含標點符號。UTF-8 格式的特殊字元。

FI
條件：名字縮寫

必須進行雜湊處理
只能使用 a-z。僅限小寫字母。UTF-8 格式的特殊字元。

ST
條件：美國州名

需雜湊處理
使用 2 個字元的 ANSI 縮寫代碼，小寫。以小寫字母正規化美國以外的州名，不可使用標點符號、特殊字元和空格。

CT
條件：城市

必須進行雜湊處理
只能使用 a-z。限小寫，不可使用標點符號、特殊字元和空格。

ZIP
條件：郵遞區號

需雜湊處理
使用小寫，且不可使用空格。如在美國，只需使用前 5 位數字。如在英國，請使用郵域／郵區／郵政部門的格式。

COUNTRY
條件：國碼／區碼

需雜湊處理

使用 2 個小寫字母的 ISO 3166-1 alpha-2 格式國碼／區碼。

MADID
條件：行動廣告主編號

不需雜湊處理

使用全部小寫，並保留連字號。

雜湊

為正規化的金鑰提供 SHA256 值，並為此值提供 HEX 表示，使用 A 到 F 的小寫。PHP 中的雜湊函數可轉換正規化的電子郵件和電話號碼。

範例結果

hash("sha256", "mary@example.com")

f1904cf1a9d73a55fa5de0ac823c4403ded71afd4c3248d00bdcd0866552bb79

hash("sha256", "15559876543")

1ef970831d7963307784fa8688e8fce101a15685d62aa765fed23f3a2c576a4e

外部識別資料

您可以使用自己的識別碼，稱為外部識別碼（EXTERN_ID）來配對廣告受眾的用戶。這可以是廣告主的任何不重複編號，例如忠誠度成員編號、用戶編號和外部 Cookie 編號。

雖然不需要雜湊處理此編號，但必須雜湊處理使用 EXTERN_ID 傳送的所有個人識別資料（PII）。

為了改善配對，在傳送編號時，您也應該使用完全相同的格式。例如，如果選擇使用 SHA256 進行雜湊，請確定使用相同的雜湊值。

您可使用這些編號做為個別金鑰來刪除自訂廣告受眾的用戶或建立新的自訂廣告受眾。如此，您就無需重新上傳任何其他配對索引鍵。如果您用雜湊的個人資訊和 EXTERN_ID 標註任何用戶，當我們將其與 Facebook 上的用戶進行配對時，我們會給予 EXTERN_ID 較低的優先順序。

EXTERN_ID 的資料保留期間為 90 天。

您可以重複使用 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

我們支援個別廣告帳號的 EXTERN_ID 參數。我們無法將某一廣告帳號的值用於任何其他廣告帳號，即使這些帳號屬於同一實體。

替換用戶 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

類型：JSON 物件

必要項目。

用於追蹤是否已上傳特定批次的用戶。必須包含連線階段編號和批次資訊。請參閱連線階段欄位。


在指定時間內，您可以將最多 10,000 名用戶新增到廣告受眾。如用戶人數超過 10,000 名，請將連線階段分為多批，這幾批連線階段一律使用同一個連線階段編號。


範例：

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

payload

類型：JSON 物件

必要項目。

用於提供您要上載給廣告受眾的資訊。必須包含架構和資料，請參閱裝載欄位以取得詳細資訊。


範例：

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

連線階段欄位

名稱說明

session_id

類型：64 位元整數

必要項目。

用於追蹤連線階段。您必須產生此識別碼，並且該編號在同一個廣告帳號中必須是唯一。

batch_seq

類型：整數

必要項目。必須從 1 開始。
當我們收到 batch_seq 為 1 時，就會開始新的替換連線階段。建議不要針對指定的 session_id 傳送序列是 1 的重複批次。
為第一個批次設定標籤很重要；連線階段的其餘批次可以是重複或 1 以外的任何數字，因為我們會使用此參數來識別連線階段的開始。只要屬於同一個連線階段，但並非第一批者，都要在第一批之後傳送。您可以將第一批想成替換操作的觸發條件/前置步驟。

last_batch_flag

類型：布林值

選用項目。

指示正在進行的替換連線階段的所有批次都已提供。如果設為 true，該連線階段將不再接受任何批次。如果您沒有設定此標示，我們會在收到第一批後 90 分鐘自動終止連線階段。在 90 分鐘後收到的任何批次也會被捨棄。

estimated_num_total

類型：整數

選用項目。

此連線階段中要上傳的預估用戶總數。供我們的系統用來改善連線階段的處理。

裝載欄位

名稱說明

schema

類型：字串或 JSON_Array_of_string

必要項目。

指定您將提供的資訊類型，可為以下清單中的單一金鑰或多重金鑰：

  • EMAIL
  • PHONE
  • GEN
  • DOBY
  • DOBM
  • DOBD
  • LN
  • FN
  • FI
  • CT
  • ST
  • ZIP
  • COUNTRY
  • MADID
  • ["hash1", "hash2", ...]。例如：["PHONE", "LN”, “FN”, “ZIP”, “DOBYM"]

data

類型：JSON_Array

必要項目。

與架構相對應的資料清單。


範例：

  • 如果結構描述為 "EMAIL"，資料應為電子郵件 sha256 雜湊的清單。
  • 如果結構描述如先前範例一樣是雜湊清單，資料應該類似 "phone_hash_value"、"LN_FN_ZIP_DOBYM"。

發出 POST 要求後，您會收到含下列欄位的回應：

名稱說明

account_id

類型：整數

帳號識別碼。

session_id

類型：整數

您先前提供的連線階段編號。

num_received

類型：整數

此連線階段目前收到的用戶總數。

num_invalid_entries

類型：整數

格式無效或無法解碼的用戶總數。如果此數字不是零，請重新檢查您的資料。

invalid_entry_samples 類型：JSON 字串陣列

目前要求中多達 100 個無效項目的範例。重新檢查您的資料。

替換 API 常見錯誤

從替換端點傳回的所有錯誤都有錯誤代碼 2650。以下是一些最常見傳回的錯誤子代碼，以及如何解決錯誤的指引。

錯誤子代碼說明因應方式

1870145

廣告受眾更新進行中

您無法替換正在更新的顧客名單自訂廣告受眾。等待廣告受眾可用性變為「正常」，然後再試一次。

1870158

替換連線階段逾時

您已達到替換批次連線階段的 90 分鐘時間限制。您的顧客名單自訂廣告受眾將會替換成您目前已上傳的內容。若要在自訂廣告受眾中加入更多內容，請等到替換程序完成，然後使用 ADD 操作。

1870147

無效的替換上傳批次

未偵測到第一個 batch_seq。batch_seq 必須從整數 1 開始。

1870159

替換連線階段已完成

此替換操作已完成，因為您上傳了 last_batch_flag==true 的批次。若要將其他批次加入自訂廣告受眾，請等到替換程序完成，然後使用 ADD 操作。

1870148

發生錯誤

未完全更新顧客名單。如果您的廣告受眾規模與預期有很大差異，請考慮再試一次。

1870144

替換不支援 DFCA 的規模

您無法替換規模有 1 億個以上的顧客名單顧客廣告受眾。

相關資源

您還可以建置及鎖定或分享其他廣告受眾類型：

另請參閱