接続オーディエンスオブジェクト
接続オーディエンスは、APIリクエスト内でインラインに定義するダイナミックなオーディエンスフィルターです。Brazeダッシュボードでセグメントを作成・管理することなく、送信時に適切なユーザーをターゲットにできます。
あらゆるオーディエンスの組み合わせに対してセグメントを事前に構築する代わりに、APIコールにフィルター条件を直接渡します。エンドポイントに応じて、このオブジェクトはaudienceまたはcustom_audienceとして渡されます。Brazeはリアルタイムで各ユーザーをその条件に照らして評価し、条件に一致するユーザーにのみメッセージを配信します。つまり、1つのキャンペーン、キャンバス、またはAPIのみのメッセージ定義で、ビジネスロジックに完全に基づいた無制限のオーディエンスバリエーションに対応できます。

Brazeは接続オーディエンスフィルターを検証します。値の型が正しくないリクエストや、不明なカスタムイベント名を含むリクエストはエラーを返します。本番環境で使用する前に、オーディエンスのペイロードをテストしてください。詳細については、フィルターの検証を参照してください。
仕組み
- メッセージを定義します。Brazeダッシュボードで API トリガーのキャンペーンまたはキャンバスを作成するか、API リクエスト内のメッセージングオブジェクトを使用してメッセージコンテンツをすべてインラインで定義します。ダイナミックなパーソナライゼーションには、トリガープロパティまたはキャンバスコンテキストを使用します。
- サポートされているエンドポイントを呼び出し、接続オーディエンスフィルターを
audienceパラメーターに含めます (/messages/live_activity/startの場合はcustom_audienceに含めます)。カスタム属性、購読ステータス、セッション履歴、セグメントのメンバーシップ、キャンペーンのエンゲージメントなどでフィルタリングできます。完全なリストについては、接続オーディエンスフィルターを参照してください。 - Braze は送信時にフィルターを評価し、条件に一致するユーザーにのみメッセージを配信します。

audience パラメーターを使用する場合、campaign_id は必須ではありません。/messages/send エンドポイントと /messages/schedule/create エンドポイントでは、事前にキャンペーンを作成しなくても、メッセージコンテンツをインラインで定義できます。ただし、キャンペーンレベルの指標 (送信数、クリック数、バウンス数など) をダッシュボードでトラッキングしたい場合は、campaign_id を含めてください。
オーディエンスはリクエストごとに定義されるため、バックエンドシステムはダッシュボードを操作することなく、あらゆるビジネスイベント (価格変更、気象警報、ライブスコアの更新など) に応じて、状況に即したメッセージをトリガーできます。
対応エンドポイント
接続オーディエンスオブジェクトは、次のエンドポイントで使用できます。
/messages/send/campaigns/trigger/send/canvas/trigger/send/messages/schedule/create/campaigns/trigger/schedule/create/canvas/trigger/schedule/create/messages/live_activity/start(custom_audienceを使用)
audience パラメーターはオブジェクトの配列をサポートしていないことに注意してください。
ユースケース
接続オーディエンスは、バックエンドシステムがイベントを検出し、動的に決定されたユーザーのグループに通知する必要があるシナリオで使用します。
| カテゴリー | 例 |
|---|---|
| 気象警報 | 気象データプロバイダーが深刻な気象イベントを検出し、preferred_city 属性が影響を受ける地域と一致するユーザーにプッシュ通知を送信します。 |
| スポーツとライブイベント | スポーツアプリが、favorite_team 属性が試合中のチームのいずれかと一致するユーザーに、リアルタイムのスコア更新や試合アラートを送信します。 |
| コンテンツとエンターテイメント | ストリーミングサービスが、新しいエピソードが公開されるたびに、favorite_shows 配列にそのシリーズのタイトルが含まれるユーザーに通知します。 |
| E コマース | オンライン小売業者が、wishlisted_products 配列に該当する商品 ID が含まれるユーザーに、値下げや再入荷のアラートを送信します。 |
| 旅行 | 旅行アプリが、booked_flight 属性が影響を受けるフライト番号と一致するユーザーにフライト遅延の通知を送信します。 |
| 金融サービス | トレーディングプラットフォームが、watchlist 配列に価格のしきい値を超えた株式ティッカーが含まれるユーザーにアラートを送信します。 |
いずれの場合も、1 つのキャンペーンまたは API のみのメッセージ定義ですべてのバリエーションを処理します。フィルター値はバックエンドが決定して API リクエストで渡すため、商品、番組、チーム、場所ごとに個別のセグメントやキャンペーンを作成する必要はありません。
リクエスト例
次の例では、/campaigns/trigger/send エンドポイントを使用して、特定の番組をお気に入りに登録し、プッシュ通知をオプトインしているユーザーをターゲットにします。
{
"campaign_id": "YOUR_CAMPAIGN_ID",
"audience": {
"AND": [
{
"custom_attribute": {
"custom_attribute_name": "favorite_shows",
"comparison": "includes_value",
"value": "Example Show"
}
},
{
"push_subscription_status": {
"comparison": "is",
"value": "opted_in"
}
}
]
},
"trigger_properties": {
"show_title": "Example Show",
"episode_title": "Season 3, Episode 1",
"deep_link": "https://example.com/shows/example-show/s3e1"
},
"broadcast": true
}
recipients を省略して audience でターゲットを指定する場合は、broadcast を true に設定します。/campaigns/trigger/send では、受信者リストを使用せずに接続オーディエンスに送信するには broadcast が必須です。broadcast が true の場合は、recipients リストを含めないでください。
オブジェクト本文
接続オーディエンスオブジェクトは、単一の接続オーディエンスフィルター、または AND 演算子と OR 演算子で組み合わせた複数の接続オーディエンスフィルターで構成されます。
複数フィルターの例:
{
"AND":
[
Connected Audience Filter,
{
"OR" :
[
Connected Audience Filter,
Connected Audience Filter
]
},
Connected Audience Filter
]
}
接続オーディエンスフィルター
複数のフィルターを AND 演算子と OR 演算子で組み合わせて、接続オーディエンスフィルターを作成します。
考慮事項
接続オーディエンスでは、このページに記載されているフィルターを使用できます。それ以外の条件でフィルタリングするには、その条件をオーディエンスセグメントに組み込み、そのセグメントを /messages/send エンドポイントの segment_id パラメーターで指定します。他のエンドポイントを使用する場合は、先に Braze ダッシュボードで API トリガーのキャンペーンまたはキャンバスにセグメントを追加する必要があります。
カスタム属性フィルター
このフィルターを使用すると、ユーザーのカスタム属性に基づいてセグメント化できます。これらのフィルターには最大 3 つのフィールドが含まれます。
{
"custom_attribute":
{
"custom_attribute_name": (String) the name of the custom attribute to filter on,
"comparison": (String) one of the allowed comparisons to make against the provided value,
"value": (String, Numeric, Boolean) the value to be compared using the provided comparison
}
}
データ型ごとに使用できる比較
カスタム属性のデータ型によって、特定のフィルターで有効な比較が決まります。
| カスタム属性のタイプ | 使用できる比較 |
|---|---|
| 文字列 | equals, not_equal, matches_regex, does_not_match_regex, exists, does_not_exist, is_any_of, is_none_of |
| 配列 | includes_value, does_not_include_value, exists, does_not_exist, is_any_of, is_none_of |
| 数値 | equals, not_equal, greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to, exists, does_not_exist |
| ブール値 | equals, not_equal, exists, does_not_exist |
| 時間 | less_than_x_days_ago, greater_than_x_days_ago, less_than_x_days_in_the_future, greater_than_x_days_in_the_future, after, before, exists, does_not_exist |
属性比較の注意事項
| 比較 | その他の考慮事項 |
|---|---|
value |
exists または does_not_exist の比較を使用する場合、value は必要ありません。before および after の比較を使用する場合、value は ISO 8601 形式の日時文字列である必要があります。 |
matches_regex |
matches_regex の比較を使用する場合、渡す値は文字列である必要があります。Braze での正規表現の使用について詳しくは、正規表現およびカスタム属性のデータ型を参照してください。 |
複数値の比較
is_any_of と is_none_of はどちらも、1 回の比較で複数の値との照合に対応しています。これらの比較は、文字列と配列の両方のカスタム属性で使用できます。
is_any_of: 属性値が指定した値のいずれかと等しいユーザーに一致します。valueには、単一の文字列または文字列の配列を指定できます。is_none_of: 属性値が指定した値のいずれにも一致しないユーザーに一致します。valueには、単一の文字列または文字列の配列を指定できます。プロファイルにその属性を持たないユーザーは、常にこの比較の条件を満たす点に注意してください。
配列属性の場合:
includes_valueでも値の配列を受け付け、ユーザーの配列に指定した値のいずれかが含まれているかどうかを確認できます。- 配列属性で
is_any_ofまたはis_none_ofを使用すると、それぞれincludes_valueおよびdoes_not_include_valueと同じように機能します。

複数値の照合には、includes_value ではなく is_any_of を使用してください。
カスタム属性の例
{
"custom_attribute":
{
"custom_attribute_name": "eye_color",
"comparison": "equals",
"value": "blue"
}
}
{
"custom_attribute":
{
"custom_attribute_name": "favorite_foods",
"comparison": "includes_value",
"value": "pizza"
}
}
{
"custom_attribute":
{
"custom_attribute_name": "last_purchase_time",
"comparison": "less_than_x_days_ago",
"value": 2
}
}
複数値の比較の例
文字列の配列を使用した is_any_of
{
"custom_attribute":
{
"custom_attribute_name": "favorite_color",
"comparison": "is_any_of",
"value": ["red", "blue", "green"]
}
}
文字列の配列を使用した is_none_of
{
"custom_attribute":
{
"custom_attribute_name": "subscription_tier",
"comparison": "is_none_of",
"value": ["bronze", "silver"]
}
}
配列を使用した includes_value (配列属性)
{
"custom_attribute":
{
"custom_attribute_name": "subscribed_products",
"comparison": "includes_value",
"value": ["1001", "1002", "1003"]
}
}
この例は、subscribed_products 配列に "1001"、"1002"、"1003" のいずれかの値が含まれているユーザーに一致します。
プッシュ購読フィルター
このフィルターを使用すると、ユーザーのプッシュ購読ステータスに基づいてセグメント化できます。
フィルター本文
{
"push_subscription_status":
{
"comparison": (String) one of the following allowed comparisons,
"value": (String) one of the following allowed values
}
}
- 使用できる比較:
is、is_not - 使用できる値:
opted_in、subscribed、unsubscribed
メール購読フィルター
このフィルターを使用すると、ユーザーのメール購読ステータスに基づいてセグメント化できます。
フィルター本文
{
"email_subscription_status":
{
"comparison": (String) one of the following allowed comparisons,
"value": (String) one of the following allowed values
}
}
- 使用できる比較:
is、is_not - 使用できる値:
opted_in、subscribed、unsubscribed
最終使用アプリフィルター
このフィルターを使用すると、ユーザーが最後にアプリを使用した日時に基づいてセグメント化できます。これらのフィルターには 2 つのフィールドが含まれます。
フィルター本文
{
"last_used_app":
{
"comparison": (String) one of the allowed comparisons listed,
"value": (String) the value to be compared using the provided comparison
}
}
- 使用できる比較:
after、before - 使用できる値: 日時 (ISO 8601 形式の文字列)
その他のフィルター
次の条件でもフィルタリングできます。各フィルターは、前述のフィルターと同じ構造で comparison と、ほとんどの場合 value を受け取ります。使用できる比較はフィルターによって異なり、サポートされていない比較を指定するとエラーが返されます。例の値は、Braze が想定する形式を示しています。
| フィルター | 対象 | 値の例 |
|---|---|---|
country_filter |
ユーザーの国。 | US |
language_filter |
ユーザーの言語。 | en |
locale_filter |
ユーザーのロケール。 | en_US |
email_filter |
ユーザーのメールアドレス。 | [email protected] |
external_user_id_filter |
ユーザーの external ID。 | external-user-123 |
phone_number_filter |
ユーザーの電話番号。 | +15555550123 |
device_gaid_filter |
ユーザーの Google 広告 ID。 | device-gaid-123 |
device_idfa_filter |
ユーザーの広告識別子 (IDFA)。 | device-idfa-123 |
device_idfv_filter |
ユーザーのベンダー識別子 (IDFV)。 | device-idfv-123 |
has_push_filter |
ユーザーがプッシュトークンを持っているかどうか。 | true |
has_background_push_filter |
ユーザーがバックグラウンドプッシュトークンを持っているかどうか。 | true |
has_email_filter |
ユーザーがメールアドレスを持っているかどうか。 | true |
email_subscription_status_filter |
ユーザーのメール購読ステータス。 | subscribed |
push_subscription_status_filter |
ユーザーのプッシュ購読ステータス。 | subscribed |
hard_bounce_filter |
ユーザーのメールアドレスがハードバウンスしたかどうか。 | true |
session_count_filter |
ユーザーが記録したセッション数。 | 5 |
first_session_since_filter |
ユーザーが最初にセッションを記録した日時。 | 2025-01-01T00:00:00Z |
last_session_since_filter |
ユーザーが最後にセッションを記録した日時。 | 2025-01-01T00:00:00Z |
created_at_filter |
ユーザープロファイルが作成された日時。 | 2025-01-01T00:00:00Z |
custom_event |
ユーザーがカスタムイベントを実行したかどうか。 | Watched Show |
custom_event_last_performed |
ユーザーが最後にカスタムイベントを実行した日時。 | 2025-01-01T00:00:00Z |
custom_events_first_since_filter |
ユーザーが最初にカスタムイベントを実行した日時。 | 2025-01-01T00:00:00Z |
segment_membership_filter |
ユーザーがセグメントに属しているかどうか。 | 00000000-0000-0000-0000-000000000001 |
received_campaign_filter |
ユーザーがキャンペーンを受信したかどうか。 | 00000000-0000-0000-0000-000000000001 |
average_order_value_calculated_attribute_filter |
ユーザーの平均注文額。 | 100.5 |
customer_lifetime_value_calculated_attribute_filter |
ユーザーの生涯価値。 | 100.5 |
refund_value_calculated_attribute_filter |
ユーザーの返金額の合計。 | 100.5 |
revenue_value_calculated_attribute_filter |
ユーザーの収益額の合計。 | 100.5 |
last_order_placed_calculated_attribute_filter |
ユーザーが最後に注文した日時。 | 2025-01-01T00:00:00Z |
total_orders_calculated_attribute_filter |
ユーザーの注文数の合計。 | 5 |
total_cancelled_orders_calculated_attribute_filter |
ユーザーのキャンセルされた注文数の合計。 | 5 |
random_number_filter |
ユーザーに割り当てられたランダムバケット番号。 | 5 |
カスタムイベントフィルターには、ワークスペースにすでに存在するカスタムイベントの名前が必要です。
ネストされたカスタム属性フィルター
このフィルターを使用すると、ネストされたカスタム属性内のプロパティに基づいてセグメント化できます。
フィルター本文
{
"nested_custom_attribute":
{
"custom_attribute_name": (String) the name of the nested custom attribute,
"nested_property_name": (String) the name of the property within that attribute,
"comparison_type": (String) the data type of the property,
"comparison": (String) one of the allowed comparisons for that data type,
"value": (String, Numeric, Boolean) the value to be compared using the provided comparison
}
}
- 使用できる比較タイプ:
boolean、day_of_year、number、string、time existsまたはdoes_not_existの比較を使用する場合、valueは必要ありません。
フィルターの検証
Brazeは、オーディエンスを構築する前に各フィルターを検証します。フィルターが検証に失敗すると、リクエストはエラーを返し、Brazeはメッセージを送信しません。
| フィルター | ルール | エラーメッセージ |
|---|---|---|
数値属性に対する custom_attribute |
value は数値である必要があります ("5" ではなく 5)。 |
Value must be a number for the attribute {ATTRIBUTE_NAME}. |
ブール値属性に対する custom_attribute |
value は文字列ではなく、true または false である必要があります。 |
Value must be a boolean for the attribute {ATTRIBUTE_NAME}. |
| カスタムイベントフィルター | イベント名がワークスペースにすでに存在している必要があります。 | Couldn't find a custom event matching {CUSTOM_EVENT_NAME} in workspace {WORKSPACE_ID} for company {COMPANY_ID}. |
| すべてのフィルター | 比較演算子がそのフィルタータイプに対して有効である必要があります。 | Invalid comparison {COMPARISON} for {FILTER} filter. |
| すべてのフィルター | 比較演算子が exists または does_not_exist でない限り、value は必須です。 |
You must specify a value. |