연결된 오디언스 오브젝트
연결된 오디언스는 API 요청 내에서 인라인으로 정의하는 동적 오디언스 필터로, Braze 대시보드에서 Segment를 생성하거나 관리하지 않고도 발송 시점에 적합한 사용자를 타겟팅할 수 있습니다.
가능한 모든 오디언스 조합에 대해 Segment를 미리 만드는 대신, API 호출에 필터 기준을 직접 전달합니다. 엔드포인트에 따라 이 오브젝트는 audience 또는 custom_audience로 전달됩니다. Braze는 각 사용자를 해당 기준에 따라 실시간으로 평가하고, 조건에 일치하는 사용자에게만 메시지를 전달합니다. 즉, 단일 Campaign, Canvas 또는 API 전용 메시지 정의로 비즈니스 로직에 따라 무제한의 오디언스 변형을 처리할 수 있습니다.

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

audience 파라미터를 사용할 때는 campaign_id가 필요하지 않습니다. /messages/send 및 /messages/schedule/create 엔드포인트를 사용하면 미리 생성된 Campaign 없이도 메시지 콘텐츠를 인라인으로 정의할 수 있습니다. 단, 대시보드에서 Campaign 수준 측정기준(발송, 클릭, 반송 등)을 추적하려면 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 배열에 해당 시리즈 제목이 포함된 사용자에게 알림을 보냅니다. |
| 이커머스 | 온라인 소매업체가 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와 동일하게 작동합니다.

다중 값 일치에는 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
마지막 앱 사용 필터
이 필터를 사용하면 사용자가 마지막으로 앱을 사용한 시점을 기준으로 세분화할 수 있습니다. 이 필터에는 두 개의 필드가 포함됩니다.
필터 본문
{
"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. |