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

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

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

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

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

ステップ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',
})

パラメーター

ステップ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

または、オーディエンスメンバーの追加に使用する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)についてのみ、特殊文字と非ローマ字アルファベット文字がサポートされています。最良のマッチング結果を得るには、特殊文字を含まないローマ字アルファベットに変換したデータを提供してください。

ハッシュ化

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

外部識別情報

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

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

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

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>/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リクエストを送信すると、次のフィールドを含む応答が返されます。

Replace APIでよくあるエラー

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

リソース

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

• ウェブサイトからのカスタムオーディエンス — 特定のページを訪問した人、またはウェブサイトでアクションを実行した人に基づいてオーディエンスを作成します。サイト上のMetaピクセルからのデータに基づいてオーディエンスを作成します。

• モバイルアプリからのカスタムオーディエンス — モバイルアプリの利用者に基づいてオーディエンスを作成します。アプリイベントから取得したデータに基づいてオーディエンスを作成します。

• 類似オーディエンス — すでに認識している利用者を指定して、Facebookアプリ上の類似する利用者を広告のターゲットにします。

• オフラインカスタムオーディエンス — 実店舗を訪れた人、カスタマーサービスに電話で問い合わせた人、その他のオフラインの手段を通じてアクションを実行した人に基づいてオーディエンスを作成します。

• キャンバスエンゲージメントオーディエンス — キャンバスにエンゲージした利用者を含むオーディエンスを作成します。

参考情報

• カスタムオーディエンス
• カスタムオーディエンスユーザー
• カスタムオーディエンスセッション
• カスタムオーディエンス利用規約