컨텍스트 변수
컨텍스트 변수는 특정 캔버스를 통한 사용자 여정 내에서 생성하고 사용할 수 있는 임시 데이터입니다. 이를 통해 지연을 개인화하고, 사용자를 동적으로 세그먼트화하며, 사용자의 프로필 정보를 영구적으로 변경하지 않고도 메시징을 풍부하게 할 수 있습니다. 컨텍스트 변수는 캔버스 세션 내에서만 존재하며, 서로 다른 캔버스나 세션 외부에서는 유지되지 않습니다.
컨텍스트 변수의 작동 방식
컨텍스트 변수는 두 가지 방법으로 설정할 수 있습니다:
- 캔버스 진입 시: 사용자가 캔버스에 진입하면 이벤트 또는 API 트리거의 데이터가 컨텍스트 변수를 자동으로 채울 수 있습니다.
- 컨텍스트 단계에서: 캔버스 내에서 컨텍스트 단계를 추가하여 수동으로 컨텍스트 변수를 정의하거나 업데이트할 수 있습니다.
각 컨텍스트 변수에는 다음이 포함됩니다:
- 이름(예:
flight_time또는subscription_renewal_date) - 데이터 유형(예: 숫자, 문자열, 시간 또는 배열)
- Liquid를 사용하거나 개인화 추가 도구를 통해 할당하는 값
정의된 컨텍스트 변수는 다음 형식으로 참조하여 캔버스 전체에서 사용할 수 있습니다: {{context.${example_variable_name}}}.
예를 들어, {{context.${flight_time}}}은 사용자의 예정된 비행 시간을 반환할 수 있습니다.
사용자가 캔버스에 진입할 때마다(이전에 진입한 적이 있더라도) 최신 진입 데이터와 캔버스 설정을 기반으로 컨텍스트 변수가 재정의됩니다. 이러한 상태 유지 방식 덕분에 각 캔버스 진입이 고유한 독립 컨텍스트를 유지할 수 있으며, 사용자가 동일한 여정 내에서 여러 활성 상태를 가지면서도 각 상태에 대한 특정 컨텍스트를 유지할 수 있습니다.
예를 들어, 고객에게 두 개의 예정된 항공편이 있는 경우, 각각 출발 시간 및 목적지와 같은 항공편별 컨텍스트 변수를 가진 두 개의 별도 여정 상태가 동시에 실행됩니다. 이를 통해 고객의 오후 2시 뉴욕행 항공편에 대한 개인화된 알림을 보내면서 내일 오전 8시 로스앤젤레스행 항공편에 대한 다른 업데이트를 보낼 수 있어, 각 메시지가 특정 예약과 관련성을 유지합니다.
고려 사항
각 컨텍스트 단계당 최대 10개의 컨텍스트 변수를 정의할 수 있습니다. 각 변수 이름은 최대 100자까지 가능하며, 문자, 숫자 또는 밑줄만 사용할 수 있습니다.
컨텍스트 변수 정의는 최대 10,240자까지 가능합니다. API 트리거 캔버스에 컨텍스트 변수를 전달하면, 컨텍스트 단계에서 생성된 변수와 동일한 네임스페이스를 공유합니다. 예를 들어, /canvas/trigger/send 엔드포인트 컨텍스트 오브젝트에서 purchased_item 변수를 보내면, {{context.${purchased_item}}}으로 참조할 수 있습니다. 컨텍스트 단계에서 해당 변수를 재정의하면, 새로운 값이 해당 사용자 여정의 API 값을 덮어쓰게 됩니다.
각 컨텍스트 단계당 최대 50KB를 저장할 수 있으며, 최대 10개의 변수에 분산됩니다. 단계의 모든 변수의 총 크기가 50KB를 초과하면, 한도를 초과하는 변수는 평가되거나 저장되지 않습니다. 예를 들어, 컨텍스트 단계에 세 개의 변수가 있는 경우:
- 변수 1: 30KB
- 변수 2: 19KB
- 변수 3: 2KB
변수 3은 이전 변수의 합이 50KB를 초과하므로 평가되거나 저장되지 않습니다.
데이터 유형
이 단계에서 생성되거나 업데이트되는 컨텍스트 변수에는 다음과 같은 데이터 유형을 할당할 수 있습니다.
컨텍스트 변수는 커스텀 이벤트와 동일한 데이터 유형 예상 형식을 가집니다.
배열 유형을 사용할 때, Braze는 값을 JSON으로 구문 분석하려고 시도하며, 이를 통해 오브젝트 배열을 성공적으로 생성할 수 있습니다. 배열 내의 오브젝트가 유효한 JSON이 아닌 경우, 결과는 단순한 문자열 배열이 됩니다.
중첩된 오브젝트 및 오브젝트 배열의 경우, as_json_string Liquid 필터를 사용하세요. 컨텍스트 단계에서 동일한 오브젝트를 생성하는 경우, as_json_string을 사용하여 오브젝트를 렌더링해야 합니다. 예를 들어 {{context.${object_array} | as_json_string }}와 같이 사용합니다.
| 데이터 유형 | 변수 이름 예시 | 예시 값 |
|---|---|---|
| 부울 | loyalty_program | true |
| 숫자 | credit_score | 740 |
| 문자열 | product_name | green_tea |
| 배열 | favorite_products | ["wireless_headphones", "smart_homehub", "fitness_tracker_swatch"] |
| 오브젝트 배열 | pet_details | [ |
| 시간(UTC 기준) | last_purchase_date | 2025-12-25T08:15:30:250-0800 |
| 오브젝트(플랫) | user_profile | { |
기본적으로 시간 데이터 유형은 UTC입니다. 시간 값을 저장하기 위해 문자열 데이터 유형을 사용하는 경우, PST와 같은 다른 시간대로 시간을 정의할 수 있습니다.
예를 들어, 생일 전날 사용자에게 메시지를 보내는 경우, 전날 발송과 관련된 Liquid 로직이 있으므로 컨텍스트 변수를 시간 데이터 유형으로 저장해야 합니다. 그러나 크리스마스(12월 25일)에 휴일 메시지를 보내는 경우, 시간을 동적 변수로 참조할 필요가 없으므로 문자열 데이터 유형을 사용하는 것이 더 적합합니다.
오브젝트 데이터 유형의 경우, 점 표기법을 사용하여 데이터 경로를 지정할 수 있습니다. 예를 들어, 컨텍스트 단계에서 다음 구조의 컨텍스트 변수 order_summary를 정의한 경우:
1
2
3
4
5
{
"shipping": {
"carrier": "overnight"
}
}
오디언스 경로 또는 결정 분할 필터에서 점 표기법을 사용하여 컨텍스트 변수 이름으로 경로를 입력합니다(예: order_summary.shipping.carrier). 필터가 평가될 때, Braze는 해당 경로를 overnight 값으로 확인합니다.
Liquid에서(예: 메시지 단계) 대신 {{context.${order_summary}.shipping.carrier}}를 사용하세요.
컨텍스트 변수 사용
캔버스에서 Liquid를 사용하는 곳이라면 어디에서나 컨텍스트 변수를 사용할 수 있습니다. 예를 들어 메시지 및 사용자 업데이트 단계에서 개인화 추가를 선택하여 사용할 수 있습니다. 메시지 단계의 인앱 메시지 및 배너의 경우, 컨텍스트 변수를 선택하여 메시지가 만료되는 시점을 결정할 수 있습니다.
예를 들어, 승객에게 다가오는 항공편 전에 VIP 라운지 이용에 대해 알리고 싶다고 가정해 보겠습니다. 이 메시지는 일등석 항공권을 구매한 승객에게만 전송해야 합니다. 컨텍스트 변수는 이러한 정보를 유연하게 추적하는 방법입니다.
사용자는 비행기 티켓을 구매할 때 캔버스에 진입하게 됩니다. 라운지 이용 자격을 결정하기 위해 컨텍스트 단계에서 lounge_access_granted라는 컨텍스트 변수를 만든 다음, 사용자 여정의 후속 단계에서 해당 컨텍스트 변수를 참조합니다.
이 컨텍스트 단계에서는 {{custom_attribute.${purchased_flight}}}를 사용하여 구매한 항공편 유형이 first_class인지 확인합니다.
다음으로 {{context.${lounge_access_granted}}}이 true인 사용자를 타겟팅하는 메시지 단계를 만들겠습니다. 이 메시지는 개인화된 라운지 정보를 포함하는 푸시 알림이 됩니다. 이 컨텍스트 변수에 따라 자격이 있는 승객은 비행 전에 관련 메시지를 받게 됩니다.
- 일등석 항공권 승객은 다음 메시지를 받게 됩니다: “VIP 전용 라운지를 이용하세요!”
- 비즈니스 및 이코노미 항공권 승객은 다음 메시지를 받게 됩니다: “항공편을 업그레이드하여 VIP 전용 라운지를 이용하세요.”
컨텍스트 단계의 정보로 개인화된 지연 옵션을 추가할 수 있습니다. 즉, 사용자를 지연시키는 변수를 선택할 수 있습니다.
행동 경로 및 종료 기준
이러한 트리거 동작에서 등록정보 필터를 컨텍스트 변수 또는 커스텀 속성과 비교하여 활용할 수 있습니다: 커스텀 이벤트 수행 및 구매하기. 이러한 동작 트리거는 기본 및 중첩 등록정보 모두에 대한 등록정보 필터를 지원합니다.
- 기본 등록정보와 비교할 때, 사용 가능한 비교는 커스텀 이벤트에 의해 정의된 등록정보의 유형과 일치합니다. 예를 들어, 문자열 등록정보는 정확히 일치 또는 정규식 일치를 지원합니다. 부울 등록정보는 true 또는 false입니다.
- 중첩 등록정보와 비교할 때, 유형이 미리 정의되어 있지 않으므로 부울, 숫자, 문자열, 시간 및 연중일에 대해 여러 데이터 유형 간의 비교를 선택할 수 있습니다. 이는 중첩 커스텀 속성에 대한 비교와 유사합니다. 비교 시 중첩 등록정보의 실제 데이터 유형과 일치하지 않는 데이터 유형을 선택하면 사용자가 행동 경로 또는 종료 기준과 일치하지 않습니다.
행동 경로 예시
커스텀 속성 비교의 경우, 동작이 수행되는 시점의 커스텀 속성 값을 사용합니다. 즉, 비교 시점에 사용자에게 해당 커스텀 속성이 채워져 있지 않거나 커스텀 속성 값이 정의된 등록정보 비교와 일치하지 않으면 행동 경로 그룹과 일치하지 않습니다. 이는 사용자가 행동 경로 단계에 진입했을 때 일치했더라도 마찬가지입니다.
다음 행동 경로는 기본 등록정보 source와 함께 커스텀 이벤트 Account_Created를 수행한 사용자를 컨텍스트 변수 app_source_variable로 정렬하도록 설정되어 있습니다.
다음 행동 경로는 특정 제품 이름 shoes에 대한 기본 등록정보 brand를 컨텍스트 변수 promoted_shoe_brand와 일치하도록 설정되어 있습니다.
종료 기준 예시
종료 기준은 사용자의 캔버스 여정 중 언제든지 다음 조건을 충족하면 캔버스를 종료한다고 명시합니다:
- 사용자가 커스텀 이벤트 장바구니 포기를 수행하고,
- 기본 등록정보 장바구니의 항목이 컨텍스트 변수
cart_item_threshold의 문자열 값과 일치할 경우.
종료 기준은 사용자의 캔버스 여정 중 언제든지 다음 조건을 충족하면 캔버스를 종료한다고 명시합니다:
- 사용자가 “book” 제품 이름에 대해 특정 구매를 수행하고,
- 해당 구매의 중첩 등록정보 “loyalty_program”이 사용자의 커스텀 속성 “VIP”와 같을 경우.
만료 설정
캔버스 메시지 단계의 배너 및 인앱 메시지의 경우, 만료에 대해 단계가 사용 가능한 후 기간을 선택한 다음 기간 개인화를 켜서 컨텍스트 변수로부터 가용 기간을 설정할 수 있습니다. 예를 들어, 컨텍스트 단계의 프로모션 또는 예약 기간과 일치시킬 수 있습니다.
기간 개인화는 해당 기간 기반 만료 옵션에 적용됩니다. 대신 특정 날짜 및 시간에를 선택하는 경우, 날짜 및 시간 컨트롤을 사용하여 만료를 설정하세요.
행동 경로 지연
행동 경로 단계에서 평가 기간 아래의 지연 개인화를 켜서 컨텍스트 변수로부터 사용자가 단계에 머무는 시간을 설정할 수 있습니다. 등급이나 지역과 같은 세부 정보에 따라 대기 기간이 사용자별로 달라야 할 때 사용하세요.
컨텍스트 변수 필터
이전에 선언된 컨텍스트 변수를 사용하는 필터를 오디언스 경로 및 결정 분할 단계에서 생성할 수 있습니다.
컨텍스트 변수 필터는 오디언스 경로 및 결정 분할 단계에서만 사용할 수 있습니다.
컨텍스트 변수는 캔버스 범위 내에서만 선언되고 접근할 수 있으므로 세그먼트에서는 참조할 수 없습니다. 컨텍스트 변수 필터는 오디언스 경로와 결정 분할 단계에서 유사하게 작동합니다. 오디언스 경로 단계는 여러 그룹을 나타내고, 결정 분할 단계는 이진 결정을 나타냅니다.
캔버스의 컨텍스트 변수에 미리 정의된 유형이 있는 것처럼, 컨텍스트 변수와 정적 값 간의 비교는 일치하는 데이터 유형을 가져야 합니다. 컨텍스트 변수 필터는 부울, 숫자, 문자열, 시간 및 연중일과 같은 여러 데이터 유형 간의 비교를 허용하며, 중첩 커스텀 속성에 대한 비교와 유사합니다.
컨텍스트 변수와 비교에 동일한 데이터 유형을 사용하세요. 예를 들어, 컨텍스트 변수가 시간 데이터 유형인 경우 시간 비교(예: “이전” 또는 “이후”)를 사용하세요. 데이터 유형이 일치하지 않는 경우(예: 시간 컨텍스트 변수에 문자열 비교 사용) 예기치 않은 동작이 발생할 수 있습니다.
“연중일”과 “시간” 필터 유형 중에서 선택하기: 날짜가 포함된 컨텍스트 변수를 필터링할 때, 날짜가 매년 반복되는지에 따라 올바른 비교 유형을 선택하세요:
- “연중일” 사용: 날짜가 매년 반복될 때(예: 생일, 기념일 또는 크리스마스와 같은 휴일). 이 비교 유형은 연도 구성요소를 무시하고 연중일(1-365/366)을 기준으로 계산합니다.
- “시간” 사용: 날짜가 반복되지 않는 절대 날짜일 때(예: 계약 종료일, 약속 날짜 또는 구독 갱신 날짜). 이 비교 유형은 연도를 포함한 전체 타임스탬프를 기준으로 계산합니다.
절대 날짜에 “연중일”을 사용하면 연도 구성요소를 무시하므로 잘못되거나 예상치 못한 결과가 발생할 수 있습니다. 예를 들어, 4월의 미래 계약 종료일이 63일 이내인지 비교할 때, “연중일”을 사용하면 날짜 번호(119 vs 359)만 비교하기 때문에 잘못 일치할 수 있습니다. 실제로 4월까지는 188일이 남아 있기 때문입니다.
일반 지침: 날짜가 매년 반복되나요? 예 → “연중일”을 사용하세요. 아니오 → “시간”을 사용하세요.
다음은 컨텍스트 변수 product_name을 정규식 /braze/와 비교하는 컨텍스트 변수 필터의 예입니다.
컨텍스트 변수 또는 커스텀 속성과 비교하기
컨텍스트 변수 또는 커스텀 속성과 비교하기 토글을 선택하면 이전에 정의된 컨텍스트 변수 또는 사용자 커스텀 속성과 비교하는 컨텍스트 변수 필터를 구성할 수 있습니다. 이는 API 트리거된 context와 같이 사용자별로 동적인 비교를 수행하거나, 컨텍스트 변수에 정의된 복잡한 비교 로직을 간소화하는 데 유용할 수 있습니다.
동적 비활성 기간 이후 사용자에게 개인화된 알림을 보내고 싶다고 가정해 보겠습니다. 지난 3일 동안 앱에 로그인하지 않은 사용자는 메시지를 받아야 합니다.
{{now | minus: 3 | append: ' days'}}로 정의된 컨텍스트 변수 re_engagement_date가 있습니다. 3 days는 사용자의 커스텀 속성으로 저장된 가변적인 양일 수 있습니다. 따라서 re_engagement_date가 last_login_date(고객 프로필에 커스텀 속성으로 저장됨) 이후인 경우, 해당 사용자에게 메시지가 전송됩니다.
다음 필터는 컨텍스트 변수 reminder_date가 컨텍스트 변수 appointment_deadline보다 이전인지 비교합니다. 이를 통해 오디언스 경로 단계에서 사용자를 그룹화하여 약속 마감일 전에 추가 알림을 받아야 하는지 여부를 결정하는 데 도움이 될 수 있습니다.
시간대 일관성 표준화
대부분의 타임스탬프 유형을 사용하는 이벤트 등록정보는 이미 캔버스에서 UTC로 되어 있지만, 몇 가지 예외가 있습니다. 캔버스 컨텍스트가 추가됨에 따라, 액션 기반 캔버스의 모든 기본 타임스탬프 이벤트 등록정보가 일관되게 UTC로 설정됩니다. 이 변경 사항은 캔버스 단계 및 메시지를 편집할 때 보다 예측 가능하고 일관된 경험을 보장하기 위한 더 넓은 노력의 일환입니다. 이 변경 사항은 특정 캔버스가 컨텍스트 단계를 사용하든 사용하지 않든 모든 액션 기반 캔버스에 영향을 미칩니다.
모든 경우에, 타임스탬프가 원하는 시간대로 표시되도록 Liquid time_zone 필터를 사용하는 것을 강력히 권장합니다. 예시는 컨텍스트 단계 문서의 자주 묻는 질문을 참조하세요.