コンテンツにスキップ

接続オーディエンスオブジェクト

接続オーディエンスは、APIリクエスト内でインラインに定義するダイナミックなオーディエンスフィルターです。Brazeダッシュボードでセグメントを作成・管理することなく、送信時に適切なユーザーをターゲットにできます。

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

仕組み

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

オーディエンスはリクエストごとに定義されるため、バックエンドシステムはダッシュボードを操作することなく、あらゆるビジネスイベント (価格変更、気象警報、ライブスコアの更新など) に応じて、状況に即したメッセージをトリガーできます。

対応エンドポイント

接続オーディエンスオブジェクトは、次のエンドポイントで使用できます。

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 と同じように機能します。

カスタム属性の例

{
  "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.
New Stuff!