カスタマーファイルカスタムオーディエンス

マーケティングAPIを使用して、ターゲットとするカスタムオーディエンスを顧客情報から作成できます。顧客情報には、メールアドレス、電話番号、氏名、生年月日、性別、所在地、アプリユーザーIDpage-scopedユーザーID、Appleの広告ID (IDFA)、Androidの広告IDなどが含まれます。

ビジネスマネージャアカウントまたは単にビジネスアカウントと呼ばれているMetaビジネスアカウントは、ビジネスポートフォリオに改称されます。この変更は、Metaのテクノロジーに段階的に導入されます。この変更の対象は化粧品のみで、MetaビジネスアカウントID(ビジネスポートフォリオID)には影響はありません。

ビジネスのデータの所有者には、このデータを作成し、管理する責任があります。これには、顧客関係管理(CRM)システムからの情報も含まれています。オーディエンスを作成するには、プライバシーを保護するためにハッシュ化した形式でデータを共有する必要があります。データのハッシュ化と正規化をご覧ください。Metaでは、このデータを当社のハッシュデータと比較し、あなたの広告のオーディエンスに追加するFacebook利用者を割り出します。

1つのオーディエンスに追加できるレコード数に制限はありませんが、一度に追加できるのは10,000件までです。カスタムオーディエンスへの変更はすぐには反映されず、通常は最大で24時間かかります。削除をリクエストしたレコードの数および/またはアカウントに含まれるカスタムオーディエンスの数によって、このリクエストの処理に要する時間が長くなります。

広告主がオーディエンスを作成し管理する方法を改善するため、2年以上どのアクティブ広告セットでも使用されていないカスタマーファイルカスタムオーディエンスには、随時、削除のためにフラグが付けられていきます。Facebookのアクションが必要な場合は、事前にFacebookに指示を提供しなければなりません。オーディエンスが「期限切れオーディエンス」ステージに移動されフラグが付けられたら、アクティブ広告セット中のフラグが付けられたオーディエンスを使用して指示するか(オーディエンスを保持するための指示とみなします)、アクティブ広告セット中でフラグが付けられたオーディエンスを使用しないことを決定する(オーディエンスを削除する指示とみなします)ことによって、Facebookに指示する必要があります。詳しくは、カスタムオーディエンスの概要に関するドキュメントをご覧ください。

コンバージョンAPIを使ってコンバージョンイベントを共有すると、追加のデータをアップロードしなくてもカスタムオーディエンスを対象としたウェブサイトを作成できます。一方、サポートされる顧客情報のアップロードを継続して、カスタマーファイルカスタムオーディエンスを作成することもできます。

新しいReplace APIを使用して、既存のユーザーを完全に削除しユーザーの新規セットに置き換えます。Replace APIでオーディエンスを更新しても、広告セットが情報収集期間に戻ることはありません。

カスタムオーディエンスの作成

ステップ1: 空のカスタムオーディエンスを作成する

API呼び出しに、subtype=CUSTOMcustomer_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', })

パラメーター

名前説明

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
ブーリアン

必須

現在進行中のReplaceセッションのすべてのバッチが提供されたことをシステムに示します。trueに設定すると、現在のリクエストが現在のセッションの最後の1つになり、このセッションではこれ以上のバッチは受け付けられません。このフラグを送信しない場合、最初のバッチを受け取ってから90分後に自動的にセッションが終了されます。90分経過後に受信したバッチもすべて破棄されます。最後のリクエストにマークを付け、これが最後のバッチであることをMetaに知らせる必要があります。

estimated_num_total
整数

任意
このセッションでアップロードされるユーザーの推定合計数。このフィールドは、セッションの処理を改善するために使われます。

応答

成功した応答では、次のフィールドを含むJSONオブジェクトが返されます。

名前説明

audience_id
数値文字列

オーディエンスの識別情報

session_id
整数

渡したセッションID

num_received
整数

このセッションで現在までに受信したユーザーの合計数

num_invalid_entries
整数

間違ったハッシュで送信されたエントリの数。そのようなエントリはマッチを返さず、カスタムオーディエンスに追加されません。これは正確な数ではなく、マッチしなかったユーザー数の範囲を表します。

invalid_entry_samples
文字列またはマップ{string: string}のJSON配列

現在のリクエストで見つかった無効なエントリのサンプル(最大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

または、オーディエンスメンバーの追加に使用するPOSTリクエストにmethodパラメーターを追加し、それを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は1つだけであり、1つの要素を持つ1つの配列にする必要があります。

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としてハッシュ化する必要があります。その他のハッシュ化メカニズムはサポートされていません。このハッシュ化は、外部識別情報アプリユーザーIDpage-scopedユーザーID、モバイル広告主IDを除くすべてのデータについて必須です。

データをハッシュ化する前に、それを正規化して処理が可能な状態にします。名(FN)と姓(LN)についてのみ、特殊文字と非ローマ字アルファベット文字がサポートされています。最良のマッチング結果を得るには、特殊文字を含まないローマ字アルファベットに変換したデータを提供してください。

こちらのCSVファイルをダウンロード

して、

以下のパラメーターで適切に正規化およびハッシュ化されたデータの例をご覧ください。



ダウンロードする(右クリック > [名前を付けてリンクを保存])
キーガイドライン

EMAIL
条件: メールアドレス

ハッシュ化が必須
先頭と末尾の空白文字を削除し、すべての文字を小文字に変換します。

PHONE
条件: 電話番号

ハッシュ化が必須
記号、文字、すべての先行ゼロを削除します。COUNTRYフィールドが指定されていない場合は、先頭に国コードを付ける必要があります。

GEN
条件: 性別

ハッシュ化が必須
男性の場合はm、女性の場合はfを使用します。

DOBY
条件: 生年月日の年

ハッシュ化が必須
YYYY形式(1900~現在の年)を使用します。

DOBM
条件: 生年月日の月

ハッシュ化が必須
MM形式(0112)を使用します。

DOBD
条件: 生年月日の日

ハッシュ化が必須
DD形式(0131)を使用します。

LNFN
条件: 姓と名

ハッシュ化が必須
a-zのみを使用します。小文字のみを使用し、句読点なしで指定します。特殊文字はUTF-8形式で指定します。

FI
条件: 名の頭文字

ハッシュ化が必須
a-zのみを使用します。必ず小文字で指定します。特殊文字はUTF-8形式で指定します。

ST
条件: 米国の州

ハッシュ化が必須
2文字のANSI略称コードを小文字で指定します。米国以外の州は、小文字のみ、句読点なし、特殊文字なし、空白文字なしに正規化します。

CT
条件: 市区町村

ハッシュ化が必須
a-zのみを使用します。小文字のみ、句読点なし、特殊文字なし、空白文字なしで指定します。

ZIP
条件: 郵便番号

ハッシュ化が必須
小文字のみを使用し、空白文字なしで指定します。米国の場合は、先頭の5文字のみを使用します。英国の場合は、地域/地区/区域の形式を使用します。

COUNTRY
条件: 国コード

ハッシュ化が必須

ISO 3166-1 alpha-2形式の2文字の小文字の国コードを使います。

MADID
条件: モバイル広告主ID

ハッシュ化は不要

すべて小文字を使い、ハイフンは残します。

ハッシュ化

正規化したキーのSHA256値と、その値のHEX表現(AからFは小文字)を提供します。PHPのハッシュ関数では、正規化されたメールアドレスと電話番号は次のように変換されます。

結果

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

f1904cf1a9d73a55fa5de0ac823c4403ded71afd4c3248d00bdcd0866552bb79

hash("sha256", "15559876543")

1ef970831d7963307784fa8688e8fce101a15685d62aa765fed23f3a2c576a4e

外部識別情報

独自の識別情報を指定して、オーディエンスに含める利用者をマッチングすることができます。この識別情報を外部識別情報(EXTERN_ID)と呼びます。外部識別情報には、広告主が提供する任意のユニークID (ロイヤルティメンバーID、ユーザーID、外部Cookie IDなど)を使用できます。

このIDをハッシュ化する必要はありませんが、EXTERN_IDを使って送信する個人を特定できる情報(PII)はすべてハッシュ化する必要があります。

マッチングを向上させるには、このIDの送信時とまったく同じ形式を使ってください。例えば、SHA256を使用してハッシュ化することを選択した場合、必ず同じハッシュ値を使ってください。

これらのIDを個別のキーとして使用して、カスタムオーディエンスからメンバーを削除したり、カスタムオーディエンスを新規作成したりできます。こうすれば、その他のマッチキーを再度アップロードする必要がなくなります。ハッシュ化された個人情報とともにEXTERN_IDを利用者にタグ付けした場合、Facebookがそれらの情報と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

Metaでは、個々の広告アカウントEXTERN_IDパラメーターをサポートしています。ある広告アカウントの値を別の広告アカウントで使用することはできません。アカウントが同じ企業や団体に属している場合であっても同様です。

Replace Users API

/<CUSTOM_AUDIENCE_ID>/usersreplaceエンドポイントでは、1つのAPI呼び出しで次の2つのアクションを実行することができます。

  • 特定のオーディエンスから既存のユーザーを完全に削除する
  • 既存のユーザーを新しいユーザーセットに置き換える

/<CUSTOM_AUDIENCE_ID>/usersreplaceエンドポイントでは、削除したいユーザーのリストをアップロードしなくても、すべての既存ユーザーを自動的に削除することができます。このエンドポイントは、/<CUSTOM_AUDIENCE_ID>/usersエンドポイントに対するPOST API呼び出しまたはDELETE API呼び出しとは異なり、オーディエンスがアクティブな広告セットの一部である場合は広告セットの情報収集期間をリセットしません。

Replace Users APIは、次の条件を満たすオーディエンスのみを処理します。

  • 置き換え処理を実行する前の既存のユーザー数は1億未満でなければなりません。オーディエンスが1億を超える場合は、/<CUSTOM_AUDIENCE_ID>/usersエンドポイントを利用してユーザーの追加と削除を行うようおすすめします。
  • サブタイプがCUSTOMに設定されている。
  • 値ベースのカスタマーファイルカスタムオーディエンスを値ベースでないカスタマーファイルカスタムオーディエンスに置き換えることも、その逆に置き換えることもできません。

スタートガイド

置換処理を開始する前に、以下の点に留意してください。

  • オーディエンスのoperation_statusが、Normalであることを確かめてください。

置換操作がすでに実行されている場合に、別の置換操作を実行することはできません。

  • /<CUSTOM_AUDIENCE_ID>/usersreplaceを使用して置換操作を実行している最中は、/<CUSTOM_AUDIENCE_ID>/usersを使用してユーザーの追加や削除はしないでください。最初の置き換え操作が完了する前に2番目の置き換え操作を実行しようとすると、置き換え操作が進行中であることを示すメッセージが表示されます。

  • 1つの置き換えセッションの最大実行時間は90分です。APIは、開始から90分以上経過したセッションのバッチを受け取っても却下します。90分を超えるバッチを送信する必要がある場合は、そのセッションの置き換え操作が終了するまで待ってから、残りのアップロードに/<CUSTOM_AUDIENCE>/usersエンドポイントの追加操作を使用してください。

  • オーディエンスの準備ができたら、/<CUSTOM_AUDIENCE_ID>/usersreplacePOST呼び出しを実行し、カスタムオーディエンスに置き換えるユーザーのリストを指定します。

    • 置き換えが始まると、オーディエンスのoperation_statusreplace_in_progressに切り替わります。
    • 置き換え操作が完了しなかった場合、オーディエンスのoperation_statusreplace_errorに切り替わります。

呼び出しパラメーター

次のパラメーターを/<CUSTOM_AUDIENCE_ID>/usersreplaceへのPOST呼び出しに指定できます。

名前説明

session

型: JSONオブジェクト

必須。

ユーザーの特定のバッチがアップロードされた場合にトラッキングするために使用します。セッションIDとバッチ情報を含める必要があります。セッションフィールドをご覧ください。


一定の時間に最大1万人をオーディエンスに追加することができます。1万人を超える場合は、セッションを複数のバッチに分割して、バッチごとに1つのセッションIDを指定してください。


例:

{
  '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_seq1のバッチを受け取ると、新しい置換セッションが始まります。特定のsession_idを持ち、シーケンスが1のバッチを複数送信することはおすすめしません。
最初のバッチを指定することが重要です。Metaでは、このパラメーターを使ってセッションの開始を識別するので、指定されていない場合は同じセッションの残りのバッチが重複したり、1以外の任意の番号になったりします。セッションの最初のバッチ以外は、すべて最初のバッチより後に送信する必要があります。最初のバッチは、置き換え操作のトリガー/事前ステップとみなしてください。

last_batch_flag

型: ブーリアン

任意。

現在進行中の置換セッションのすべてのバッチが提供されたことを示します。trueに設定されている場合、以後そのセッションに関してバッチを受け付けることはありません。このフラグを設定しない場合、最初のバッチを受け取ってから90分後に自動的にセッションが終了されます。90分経過後に受信したバッチもすべて破棄されます。

estimated_num_total

型: 整数

任意。

このセッションでアップロードされるユーザーの推定合計数。セッションの処理を改善するためにシステムで使用されます。

ペイロードフィールド

名前説明

schema

型: 文字列またはJSON_Array_of_string

必須。

提供する情報のタイプを指定します。次のリストに示す1つまたは複数のキーを使用できます。

  • 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

型: 整数

以前提供したセッションID。

num_received

型: 整数

このセッションで現在までに受信したユーザーの合計数。

num_invalid_entries

型: 整数

無効な形式のユーザーまたはデコードできなかったユーザーの合計数。この数字がゼロでない場合は、データを再チェックします。

invalid_entry_samples 型: JSON文字列配列

現在のリクエスト内の無効なエントリ(最大100件)。データを再チェックします。

Replace APIでよくあるエラー

Replaceエンドポイントから返されるすべてのエラーのエラーコードは2650になります。以下に、最も一般的に返されるエラーサブコードのいくつかと、解決方法のガイダンスを紹介します。

サブコードエラー説明対処法

1870145

オーディエンスのアップデート中

アップデート中の顧客リストカスタムオーディエンスを置換することはできません。オーディエンスが「正常」になるまで待ってから、再試行してください。

1870158

置換セッションがタイムアウト

置換バッチセッションの90分の制限時間に達しました。顧客リストカスタムオーディエンスは、その時点までにアップロードした内容で置き換えられます。カスタムオーディエンスにさらに追加するには、置換処理が終了するまで待機してから、ADD操作を使用します。

1870147

置換のアップロードバッチが無効

最初のbatch_seqが検出されませんでした。batch_seqは整数1で始める必要があります。

1870159

置換セッション終了

last_batch_flag==trueを指定してアップロードされているため、この置換操作はすでに終了しています。カスタムオーディエンスにバッチを追加するには、置換処理が終了するまで待機してから、ADD操作をし用意します。

1870148

不具合の発生

顧客リストのアップデートは完了していません。オーディエンスのサイズが予期したものと大きく異なる場合、再試行を検討してください。

1870144

置換でサポートされていないDFCAサイズ

1億人以上のサイズの顧客リストカスタムオーディエンスを置換することはできません。

リソース

作成してターゲット設定したり共有したりできるその他のタイプのオーディエンスには次のものがあります。