マーケティングAPIを使用して、ターゲットとするカスタムオーディエンスを顧客情報から作成できます。顧客情報には、メールアドレス、電話番号、氏名、生年月日、性別、所在地、アプリユーザーID、page-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でオーディエンスを更新しても、広告セットが情報収集期間に戻ることはありません。
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
名前 | 説明 |
---|---|
| カスタムオーディエンスの顧客情報が最初に収集された際の収集方法を記述します。
|
| カスタムオーディエンスの名前 |
| カスタムオーディエンスの説明 |
| カスタムオーディエンスのタイプ |
/{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>"] ] } |
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
のフィールド名前 | 説明 |
---|---|
| 必須 |
| 必須 |
| 必須 現在進行中のReplaceセッションのすべてのバッチが提供されたことをシステムに示します。 |
| 任意 |
成功した応答では、次のフィールドを含むJSONオブジェクトが返されます。
名前 | 説明 |
---|---|
| オーディエンスの識別情報 |
| 渡したセッションID |
| このセッションで現在までに受信したユーザーの合計数 |
| 間違ったハッシュで送信されたエントリの数。そのようなエントリはマッチを返さず、カスタムオーディエンスに追加されません。これは正確な数ではなく、マッチしなかったユーザー数の範囲を表します。 |
| 現在のリクエストで見つかった無効なエントリのサンプル(最大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
としてハッシュ化する必要があります。その他のハッシュ化メカニズムはサポートされていません。このハッシュ化は、外部識別情報、アプリユーザーID、page-scopedユーザーID、モバイル広告主IDを除くすべてのデータについて必須です。
データをハッシュ化する前に、それを正規化して処理が可能な状態にします。名(FN
)と姓(LN
)についてのみ、特殊文字と非ローマ字アルファベット文字がサポートされています。最良のマッチング結果を得るには、特殊文字を含まないローマ字アルファベットに変換したデータを提供してください。
キー | ガイドライン |
---|---|
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 |
| ハッシュ化が必須 ISO 3166-1 alpha-2形式の2文字の小文字の国コードを使います。 |
| ハッシュ化は不要 すべて小文字を使い、ハイフンは残します。 |
正規化したキーのSHA256
値と、その値のHEX
表現(AからFは小文字)を提供します。PHPのハッシュ関数では、正規化されたメールアドレスと電話番号は次のように変換されます。
例 | 結果 |
---|---|
| f1904cf1a9d73a55fa5de0ac823c4403ded71afd4c3248d00bdcd0866552bb79 |
| 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
パラメーターをサポートしています。ある広告アカウントの値を別の広告アカウントで使用することはできません。アカウントが同じ企業や団体に属している場合であっても同様です。
/<CUSTOM_AUDIENCE_ID>/usersreplace
エンドポイントでは、1つのAPI呼び出しで次の2つのアクションを実行することができます。
/<CUSTOM_AUDIENCE_ID>/usersreplace
エンドポイントでは、削除したいユーザーのリストをアップロードしなくても、すべての既存ユーザーを自動的に削除することができます。このエンドポイントは、/<CUSTOM_AUDIENCE_ID>/users
エンドポイントに対するPOST API呼び出しまたはDELETE API呼び出しとは異なり、オーディエンスがアクティブな広告セットの一部である場合は広告セットの情報収集期間をリセットしません。
Replace Users APIは、次の条件を満たすオーディエンスのみを処理します。
/<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>/usersreplace
にPOST
呼び出しを実行し、カスタムオーディエンスに置き換えるユーザーのリストを指定します。
operation_status
はreplace_in_progress
に切り替わります。 operation_status
はreplace_error
に切り替わります。次のパラメーターを/<CUSTOM_AUDIENCE_ID>/usersreplace
へのPOST
呼び出しに指定できます。
名前 | 説明 |
---|---|
型: JSONオブジェクト | 必須。 ユーザーの特定のバッチがアップロードされた場合にトラッキングするために使用します。セッションIDとバッチ情報を含める必要があります。セッションフィールドをご覧ください。 一定の時間に最大1万人をオーディエンスに追加することができます。1万人を超える場合は、セッションを複数のバッチに分割して、バッチごとに1つのセッションIDを指定してください。 例: { 'session_id':9778993, 'batch_seq':10, 'last_batch_flag':true, 'estimated_num_total':99996 } |
型: JSONオブジェクト | 必須。 オーディエンスにアップロードする情報を指定するために使用します。スキーマとデータを含める必要があります —詳しくは、「ペイロードフィールド」をご覧ください。 例: { "schema":"EMAIL", "data":["<HASHED_EMAIL>", "<HASHED_EMAIL>", "<HASHED_EMAIL>" ] } |
名前 | 説明 |
---|---|
型: 64ビット整数 | 必須。 セッションをトラッキングするために使用します。この識別情報を生成する必要がありますが、この数字は同一広告アカウント内でユニークでなければなりません。 |
型: 整数 | 必須。必ず |
型: ブーリアン | 任意。 現在進行中の置換セッションのすべてのバッチが提供されたことを示します。trueに設定されている場合、以後そのセッションに関してバッチを受け付けることはありません。このフラグを設定しない場合、最初のバッチを受け取ってから90分後に自動的にセッションが終了されます。90分経過後に受信したバッチもすべて破棄されます。 |
型: 整数 | 任意。 このセッションでアップロードされるユーザーの推定合計数。セッションの処理を改善するためにシステムで使用されます。 |
名前 | 説明 |
---|---|
型: 文字列または | 必須。 提供する情報のタイプを指定します。次のリストに示す1つまたは複数のキーを使用できます。
|
型: JSON_Array | 必須。 スキーマに対応したデータのリスト。 例:
|
POST
リクエストを送信すると、次のフィールドを含む応答が返されます。
名前 | 説明 |
---|---|
型: 整数 | アカウント識別情報。 |
型: 整数 | 以前提供したセッションID。 |
型: 整数 | このセッションで現在までに受信したユーザーの合計数。 |
型: 整数 | 無効な形式のユーザーまたはデコードできなかったユーザーの合計数。この数字がゼロでない場合は、データを再チェックします。 |
| 現在のリクエスト内の無効なエントリ(最大100件)。データを再チェックします。 |
Replaceエンドポイントから返されるすべてのエラーのエラーコードは2650になります。以下に、最も一般的に返されるエラーサブコードのいくつかと、解決方法のガイダンスを紹介します。
サブコードエラー | 説明 | 対処法 |
---|---|---|
1870145 | オーディエンスのアップデート中 | アップデート中の顧客リストカスタムオーディエンスを置換することはできません。オーディエンスが「正常」になるまで待ってから、再試行してください。 |
1870158 | 置換セッションがタイムアウト | 置換バッチセッションの90分の制限時間に達しました。顧客リストカスタムオーディエンスは、その時点までにアップロードした内容で置き換えられます。カスタムオーディエンスにさらに追加するには、置換処理が終了するまで待機してから、 |
1870147 | 置換のアップロードバッチが無効 | 最初の |
1870159 | 置換セッション終了 |
|
1870148 | 不具合の発生 | 顧客リストのアップデートは完了していません。オーディエンスのサイズが予期したものと大きく異なる場合、再試行を検討してください。 |
1870144 | 置換でサポートされていないDFCAサイズ | 1億人以上のサイズの顧客リストカスタムオーディエンスを置換することはできません。 |
作成してターゲット設定したり共有したりできるその他のタイプのオーディエンスには次のものがあります。
ウェブサイトからのカスタムオーディエンス — 特定のページを訪問した人、またはウェブサイトでアクションを実行した人に基づいてオーディエンスを作成します。サイト上のMetaピクセルからのデータに基づいてオーディエンスを作成します。
モバイルアプリからのカスタムオーディエンス — モバイルアプリの利用者に基づいてオーディエンスを作成します。アプリイベントから取得したデータに基づいてオーディエンスを作成します。
類似オーディエンス — すでに認識している利用者を指定して、Facebookアプリ上の類似する利用者を広告のターゲットにします。
オフラインカスタムオーディエンス — 実店舗を訪れた人、カスタマーサービスに電話で問い合わせた人、その他のオフラインの手段を通じてアクションを実行した人に基づいてオーディエンスを作成します。
キャンバスエンゲージメントオーディエンス — キャンバスにエンゲージした利用者を含むオーディエンスを作成します。