マーケティングAPI

モバイルアプリのカスタムオーディエンス

アプリ内での利用者のアクションに基づいて、条件を満たすオーディエンスを作成します。この機能を使用すると、次のようなオーディエンスを作成できます:

  • 「過去10日以内にレベル8をクリアした」
  • 「過去8日以内にアプリを使用したが、何も購入しなかった」
  • 「カートに追加したが、購入しなかった」

このソリューションは、Facebook SDK、アプリイベントAPI、またはモバイル測定パートナーを介して、ログに記録される名前付きイベントを使用します。記録されるイベントの例としては、「インストールした」、「カートに追加した」、「購入した」、「レベルに達した」などがあります。

制限

  • エンゲージメントカスタムオーディエンスのsubtypeは、動画の場合のみサポートされます。
  • iOS 14.5のSKAdNetworkキャンペーンでは、包含ターゲット設定用のモバイルアプリのカスタムオーディエンスは、POST /{ad-account-id}/adsetsエンドポイントでサポートされなくなりました。
  • 新しいiOS 14.5のアプリのインストールキャンペーンでは、アプリ接続ターゲット設定を使用できなくなります。

オーディエンスの作成

モバイルアプリからカスタムオーディエンスを作成するには、広告アカウントが広告マネージャでカスタムオーディエンスのサービス利用規約に同意する必要があります。利用規約に署名するには:

  • そのためには、広告アカウントの管理者、開発者、またはインサイトユーザーである必要があります。
  • 該当の広告アカウントが、アプリの設定で広告アカウントとしてリストされている必要があります。

オーディエンスを作成するには:

curl -X POST \
  -F 'name="My Test Website Custom Audience"' \
  -F 'rule={
       "inclusions": {
         "operator": "or",
         "rules": [
           {
             "event_sources": [
               {
                 "id": "<APP_ID>",
                 "type": "app"
               }
             ],
             "retention_seconds": 8400,
             "filter": {
               "operator": "and",
               "filters": [
                 {
                   "field": "event",
                   "operator": "eq",
                   "value": "fb_mobile_purchase"
                 }
               ]
             }
           }
         ]
       }
     }' \
  -F 'prefill=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences
Open In Graph API Explorer
'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 Test Website Custom Audience',
  'rule' : {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<appID>','type':'app'}],'retention_seconds':8400,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'fb_mobile_purchase'}]}}]}},
  'prefill' : '1',
};
const customaudiences = (new AdAccount(id)).createCustomAudience(
  fields,
  params
);
logApiCallResult('customaudiences api call complete.', customaudiences);
Open In Graph API Explorer
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 Test Website Custom Audience',
  'rule' => array('inclusions' => array('operator' => 'or','rules' => array(array('event_sources' => array(array('id' => '<appID>','type' => 'app')),'retention_seconds' => 8400,'filter' => array('operator' => 'and','filters' => array(array('field' => 'event','operator' => 'eq','value' => 'fb_mobile_purchase'))))))),
  'prefill' => '1',
);
echo json_encode((new AdAccount($id))->createCustomAudience(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
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 Test Website Custom Audience',
  'rule': {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<appID>','type':'app'}],'retention_seconds':8400,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'fb_mobile_purchase'}]}}]}},
  'prefill': '1',
}
print AdAccount(id).create_custom_audience(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
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 Test Website Custom Audience\")
      .setRule(\"{\\"inclusions\\":{\\"operator\\":\\"or\\",\\"rules\\":[{\\"event_sources\\":[{\\"id\\":\\"<appID>\\",\\"type\\":\\"app\\"}],\\"retention_seconds\\":8400,\\"filter\\":{\\"operator\\":\\"and\\",\\"filters\\":[{\\"field\\":\\"event\\",\\"operator\\":\\"eq\\",\\"value\\":\\"fb_mobile_purchase\\"}]}}]}}\")
      .setPrefill(true)
      .execute();

  }
}
Open In Graph API Explorer
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 Test Website Custom Audience',
    rule: {'inclusions':{'operator':'or','rules':[{'event_sources':[{'id':'<appID>','type':'app'}],'retention_seconds':8400,'filter':{'operator':'and','filters':[{'field':'event','operator':'eq','value':'fb_mobile_purchase'}]}}]}},
    prefill: '1',
})
Open In Graph API Explorer

成功した場合、オーディエンスのidが返されます。最も関連性の高いパラメーターは次のとおりです。

名前 説明

name

型:文字列

必須。

カスタムオーディエンスの名前

description

型:文字列

任意。

カスタムオーディエンスの説明。

rule

型: JSONオブジェクト

任意。

オーディエンスを定義するルール。「オーディエンスルール」をご覧ください。

各広告アカウントで、モバイルアプリからのカスタムオーディエンスを使用して、最大200のカスタムオーディエンスを作成できます。以下に対してPOSTリクエストを送信します:

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

次のフィールドを使用します:

名前 説明

name

型: 文字列

必須。

カスタムオーディエンスの名前

retention_days

型: 整数

必須。

利用者をこのオーディエンスに留めておく期間。最小値は1です。最大値は180です。


retention_daysが14の場合、13日目にオーディエンスメンバーが条件に一致するアプリイベントをトリガーすると、Facebookはオーディエンスに留めておく期間をさらに14日延長します。利用者は、自分がトリガーした最後の一致イベントからN日間オーディエンスに留まります。

rule

型: JSONオブジェクト

必須。

オーディエンスを定義するルール。「オーディエンスルール」をご覧ください

オーディエンスルール

誰をカスタムオーディエンスに追加するかを決めるために、アプリ内のイベントに基づいてルールを定義します。ルールはキーと値のペアを持つJSONオブジェクトであり、複数のアプリイベントを参照できます。特定のイベントやそのパラメーターに関するルール、集計も定義することができます。詳しくは、「オーディエンスルール」をご覧ください。参考情報:

  • オーディエンスルールの構文
  • ルールセットの構文
  • 包含ルールと除外ルールの構文: event_sourcesの下で、idをアプリのIDに設定し、typeをappに設定します。
  • フィルター
  • フィルタールール:
    • フィルターでイベントを指定する場合は、fieldとして'event'を使用します。アプリによって送信されたアプリイベントに一致するパラメーター(例: "_appVersion"、"_value"など)
    • field属性を"event"に設定する場合は、値をイベント名に設定する必要があります。ピクセルから報告されたアプリイベントとパラメーターを参照するには、アプリイベントAPIを使用します。
  • 集計関数: モバイルアプリのカスタムオーディエンスでは、次の集計関数を使用できます: "count"、"sum"、"avg"、"min"、"max"。

モバイルアプリのカスタムオーディエンスのルールの例

標準イベントの例

アプリID 55064006の過去30日間のすべてのモバイルアプリ購入者:

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "fb_mobile_purchase"
                        }
                    ]
                }
            }
        ]
    }
}

パラメーターを指定したカスタムイベントの例

アプリID 55064006に対して過去30日間にカスタム“timeOnPanel”イベントを返したすべての利用者:

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "timeOnPanel"
                        }
                    ]
                }
            }
        ]
    }
}

イベント値が30より大きく、色が“red”または“blue”で、お気に入りのデザートに“banana”が含まれるカスタム“timeOnPanel”イベントを返したすべての利用者:

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app",
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "timeOnPanel",
                        },
                        {
                            "field": "_value",
                            "operator": ">",
                            "value": 30,
                        },
                        {
                            "field": "color",
                            "operator": "is_any",
                            "value": ["red", "blue"],
                        },
                        {
                            "field": "favoriteDessert",
                            "operator": "contains",
                            "value": "banana",
                        }
                    ]
                }
            }
        ]
    }
}

集計の例

過去30日間の購入に基づいた購入の上位20%

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "fb_mobile_purchase"
                        }
                    ]
                }
                "aggregation": {
                    "type": "count",
                    "method": "percentile",
                    "operator": "in_range",
                    "from": 75,  
                    "to": 100,
                }
            }
        ]
    }
}

除外の例

次の例では、カートに追加したが購入しなかった利用者を包含しています:

{
    "inclusions: {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "add_to_cart"
                        }
                    ]
                }
            }
        ]
    },
    "exclusions": {
        "operator": "or",
        "rules": [    
            {
                "event_sources": [
                    {
                        "id": 55064006, 
                        "type": "app"
                    }
                ],
                "retention_seconds: 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "=",
                            "value": "fb_mobile_purchase"
                        }
                    ]
                }
            }
        ]
    }
}

アプリイベントAPI

アプリがFacebookに報告したアプリイベントとパラメーターをクエリします。これらのイベントとパラメーターは、カスタムオーディエンスの作成に直接使用できます。管理者、開発者、または広告主の役割を持つapp_idに関連付けられたアクセストークンが必要です。

以下に対してGETリクエストを送信します:

https://graph.facebook.com/<API_VERSION>/<APP_ID>/app_event_types

応答はJSON形式で、次のフィールドを持つJSONディクショナリのdata配列が含まれます:

名前 説明

event_name

型: 文字列

ルールで使用するアプリイベントタイプ。

display_name

型: 文字列

人間が読める形式の、イベントタイプの名前です

description

型: 文字列

標準イベントの詳細な説明です

parameters

型: 配列

このイベントのパラメーターを記述したJSONディクショナリの配列: {"parameter_name": "fb_currency","display_name": "Currency","description": "Currency for event"}


parameter_name: ルールで使用する、アプリのパラメータータイプ(文字列)


display_name: 人間が読める形式のイベントタイプ名(文字列)


description: 標準パラメーターの場合、パラメーターの詳細な説明(文字列)


オーディエンスの管理

リソース