콘텐츠로 건너뛰기

연결된 오디언스 오브젝트

연결된 오디언스는 API 요청 내에서 인라인으로 정의하는 동적 오디언스 필터로, Braze 대시보드에서 Segment를 생성하거나 관리하지 않고도 발송 시점에 적합한 사용자를 타겟팅할 수 있습니다.

가능한 모든 오디언스 조합에 대해 Segment를 미리 만드는 대신, API 호출에 필터 기준을 직접 전달합니다. 엔드포인트에 따라 이 오브젝트는 audience 또는 custom_audience로 전달됩니다. Braze는 각 사용자를 해당 기준에 따라 실시간으로 평가하고, 조건에 일치하는 사용자에게만 메시지를 전달합니다. 즉, 단일 Campaign, Canvas 또는 API 전용 메시지 정의로 비즈니스 로직에 따라 무제한의 오디언스 변형을 처리할 수 있습니다.

작동 방식

  1. Braze 대시보드에서 API 트리거 Campaign 또는 Canvas를 생성하여 메시지를 정의하거나, API 요청에서 메시징 오브젝트를 사용해 메시지 콘텐츠 전체를 인라인으로 정의합니다. 동적 개인화에는 트리거 속성정보 또는 Canvas 컨텍스트를 사용합니다.
  2. 지원되는 엔드포인트를 호출하고 연결된 오디언스 필터를 audience 파라미터에 포함합니다. /messages/live_activity/start의 경우 custom_audience에 포함합니다. 커스텀 속성, 가입 상태, 세션 기록, Segment 멤버십, Campaign 인게이지먼트 등을 기준으로 필터링할 수 있습니다. 전체 목록은 연결된 오디언스 필터를 참조하세요.
  3. Braze는 발송 시점에 필터를 평가하여 기준에 일치하는 사용자에게만 메시지를 전달합니다.

오디언스가 요청마다 정의되므로, 백엔드 시스템은 대시보드 개입 없이도 모든 비즈니스 이벤트(가격 변동, 기상 경보, 실시간 점수 업데이트 등)에 대응하여 상황에 맞는 메시지를 트리거할 수 있습니다.

호환 엔드포인트

연결된 오디언스 오브젝트는 다음 엔드포인트에서 사용할 수 있습니다.

audience 파라미터는 오브젝트 배열을 지원하지 않습니다.

사용 사례

연결된 오디언스는 백엔드 시스템이 이벤트를 감지하고, 동적으로 결정되는 사용자 집합에 알림을 보내야 하는 시나리오에 사용합니다.

카테고리 예시
날씨 알림 기상 데이터 제공업체가 악천후 이벤트를 감지하면, preferred_city 속성이 영향을 받는 지역과 일치하는 사용자에게 푸시 알림을 보냅니다.
스포츠 및 실시간 이벤트 스포츠 앱이 favorite_team 속성이 경기 중인 팀 중 하나와 일치하는 사용자에게 실시간 점수 업데이트나 경기 알림을 보냅니다.
콘텐츠 및 엔터테인먼트 스트리밍 서비스가 새 에피소드가 공개될 때마다 favorite_shows 배열에 해당 시리즈 제목이 포함된 사용자에게 알림을 보냅니다.
이커머스 온라인 소매업체가 wishlisted_products 배열에 관련 제품 ID가 포함된 사용자에게 가격 인하 또는 재입고 알림을 보냅니다.
여행 여행 앱이 booked_flight 속성이 영향을 받는 항공편 번호와 일치하는 사용자에게 항공편 지연 알림을 보냅니다.
금융 서비스 트레이딩 플랫폼이 watchlist 배열에 가격 임계값을 넘은 주식 종목 코드가 포함된 사용자에게 알림을 보냅니다.

어떤 경우든 단일 Campaign 또는 API 전용 메시지 정의 하나로 모든 변형을 처리합니다. 백엔드에서 필터 값을 결정해 API 요청에 전달하므로, 제품, 프로그램, 팀, 위치마다 별도의 Segment나 Campaign을 만들 필요가 없습니다.

요청 예시

다음 예시는 /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 연산자로 여러 필터를 조합하여 연결된 오디언스 필터를 만들 수 있습니다.

고려 사항

연결된 오디언스는 다음 기준으로 사용자를 필터링할 수 없습니다.

  • 기본 속성
  • 커스텀 이벤트
  • Segments
  • 메시지 인게이지먼트 이벤트
  • 중첩 커스텀 속성

이러한 필터를 사용하려면 해당 필터를 오디언스 Segment에 포함한 다음, /messages/send 엔드포인트의 segment_id 파라미터에 해당 Segment를 지정하는 것이 좋습니다. /campaigns/trigger/send 및 /canvas/trigger/send 엔드포인트도 브로드캐스트 발송 시 segment_id를 지원합니다. 다른 엔드포인트를 사용하는 경우에는 먼저 Braze 대시보드에서 API 트리거 Campaign 또는 Canvas에 Segment를 추가해야 합니다. 중첩 속성으로 필터링해야 하는 경우에는 대신 표준 Segment를 사용하세요.

커스텀 속성 필터

이 필터를 사용하면 사용자의 커스텀 속성을 기준으로 세분화할 수 있습니다. 이 필터에는 최대 세 개의 필드가 포함됩니다.

{
  "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는 모두 한 번의 비교에서 여러 값과의 일치를 지원합니다. 이 비교는 문자열 및 배열 커스텀 속성 모두에서 작동합니다.

  • 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

마지막 앱 사용 필터

이 필터를 사용하면 사용자가 마지막으로 앱을 사용한 시점을 기준으로 세분화할 수 있습니다. 이 필터에는 두 개의 필드가 포함됩니다.

필터 본문

{
  "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 사용자의 외부 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 사용자가 Segment에 속해 있는지 여부 00000000-0000-0000-0000-000000000001
received_campaign_filter 사용자가 Campaign을 수신했는지 여부 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!