컨텍스트 변수

컨텍스트 변수는 특정 Canvas를 통한 사용자 여정 내에서 생성하고 사용할 수 있는 임시 데이터입니다. 컨텍스트 변수를 사용하면 사용자의 프로필 정보를 영구적으로 변경하지 않고도 지연을 개인화하고, 사용자를 동적으로 세그먼트하며, 메시징을 풍부하게 만들 수 있습니다. 컨텍스트 변수는 Canvas 세션 내에서만 존재하며, 다른 Canvas나 세션 외부에서는 유지되지 않습니다.

컨텍스트 변수의 작동 방식

컨텍스트 변수는 두 가지 방법으로 설정할 수 있습니다:

• Canvas 진입 시: 사용자가 Canvas에 진입하면, 이벤트 또는 API 트리거의 데이터가 자동으로 컨텍스트 변수에 채워집니다.
• 컨텍스트 단계에서: 컨텍스트 단계를 추가하여 Canvas 내부에서 수동으로 컨텍스트 변수를 정의하거나 업데이트할 수 있습니다.

각 컨텍스트 변수에는 다음이 포함됩니다:

• 이름(예: flight_time 또는 subscription_renewal_date)
• 데이터 유형(예: 숫자, 문자열, 시간 또는 배열)
• Liquid 또는 개인화 추가 도구를 사용하여 할당하는 값

정의된 컨텍스트 변수는 다음 형식으로 참조하여 Canvas 전체에서 사용할 수 있습니다: {{context.${example_variable_name}}}.

예를 들어, {{context.${flight_time}}}은 사용자의 예정된 비행 시간을 반환할 수 있습니다.

사용자가 Canvas에 진입할 때마다—이전에 진입한 적이 있더라도—컨텍스트 변수는 최신 진입 데이터와 Canvas 설정에 따라 다시 정의됩니다. 이러한 상태 기반 접근 방식을 통해 각 Canvas 진입은 자체적인 독립 컨텍스트를 유지할 수 있으며, 사용자는 동일한 여정 내에서 각 상태에 대한 특정 컨텍스트를 유지하면서 여러 활성 상태를 가질 수 있습니다.

예를 들어, 고객이 예정된 항공편이 두 편 있는 경우, 각각 출발 시간과 목적지와 같은 고유한 항공편별 컨텍스트 변수를 가진 두 개의 별도 여정 상태가 동시에 실행됩니다. 이를 통해 오후 2시 뉴욕행 항공편에 대한 개인화된 리마인더를 보내는 동시에, 내일 오전 8시 로스앤젤레스행 항공편에 대한 다른 업데이트를 보낼 수 있으므로 각 메시지가 특정 예약에 관련된 상태를 유지합니다.

고려 사항

Context 단계당 최대 10개의 컨텍스트 변수를 정의할 수 있습니다. 각 변수 이름은 최대 100자까지 가능하며, 문자, 숫자 또는 밑줄만 사용해야 합니다.

컨텍스트 변수 정의는 최대 10,240자까지 가능합니다. API 트리거 Canvas에 컨텍스트 변수를 전달하는 경우, Context 단계에서 생성된 변수와 동일한 네임스페이스를 공유합니다. 예를 들어, /canvas/trigger/send 엔드포인트 컨텍스트 객체에서 변수 purchased_item을 전송하면, {{context.${purchased_item}}}로 참조할 수 있습니다. Context 단계에서 해당 변수를 다시 정의하면, 새 값이 해당 사용자 여정에 대한 API 값을 덮어씁니다.

Context 단계당 최대 50KB를 저장할 수 있으며, 최대 10개의 변수에 분산됩니다. 단계 내 모든 변수의 총 크기가 50KB를 초과하면, 한도를 초과하는 변수는 평가되거나 저장되지 않습니다. 예를 들어, Context 단계에 세 개의 변수가 있는 경우:

• 변수 1: 30KB
• 변수 2: 19KB
• 변수 3: 2KB

이전 변수의 합이 50KB를 초과하므로 변수 3은 평가되거나 저장되지 않습니다.

데이터 유형

해당 단계에서 생성하거나 업데이트한 컨텍스트 변수에는 다음 데이터 유형을 할당할 수 있습니다.

참고

컨텍스트 변수는 이벤트 속성정보와 동일한 데이터 유형 형식을 따릅니다.

배열 유형을 사용하면 Braze는 값을 JSON으로 파싱하려고 시도하며, 이를 통해 객체 배열을 성공적으로 생성할 수 있습니다. 배열 내의 객체가 유효한 JSON이 아닌 경우, 결과는 단순 문자열 배열이 됩니다.

중첩 객체 및 객체 배열의 경우 as_json_string Liquid 필터를 사용하세요. 컨텍스트 단계에서 동일한 객체를 생성하는 경우, as_json_string을 사용하여 객체를 렌더링해야 합니다. 예: {{context.${object_array} | as_json_string }}

기본적으로 시간 데이터 유형은 UTC 기준입니다. 문자열 데이터 유형을 사용하여 시간 값을 저장하는 경우, PST와 같은 다른 시간대로 시간을 정의할 수 있습니다.

예를 들어, 사용자의 생일 전날에 메시지를 보내는 경우, 전날 발송하는 것과 관련된 Liquid 로직이 있으므로 컨텍스트 변수를 시간 데이터 유형으로 저장합니다. 그러나 크리스마스(12월 25일)에 휴일 메시지를 보내는 경우, 시간을 동적 변수로 참조할 필요가 없으므로 문자열 데이터 유형을 사용하는 것이 더 적합합니다.

객체 데이터 유형의 경우 점 표기법(dot notation)을 사용하여 데이터의 경로를 지정할 수 있습니다. 예를 들어, 컨텍스트 단계에서 다음과 같은 구조로 컨텍스트 변수 order_summary를 정의한 경우:

1
2
3
4
5

{
  "shipping": {
    "carrier": "overnight"
  }
}

오디언스 경로 또는 결정 분할 필터에서 점 표기법을 사용하여 컨텍스트 변수 이름으로 경로를 입력합니다(예: order_summary.shipping.carrier). 필터가 평가되면 Braze는 해당 경로를 overnight 값으로 확인합니다.

Liquid에서(메시지 단계 등) 대신 {{context.${order_summary}.shipping.carrier}}를 사용합니다.

컨텍스트 변수 사용하기

메시지 및 사용자 업데이트 단계에서 개인화 추가를 선택하여 Canvas에서 Liquid를 사용하는 모든 곳에서 컨텍스트 변수를 사용할 수 있습니다. 메시지 단계의 인앱 메시지 및 배너에서는 컨텍스트 변수를 선택하여 메시지가 만료되는 시점을 결정할 수 있습니다.

예를 들어, 승객에게 다가오는 항공편 전에 VIP 라운지 이용 안내를 알리고 싶다고 가정해 보겠습니다. 이 메시지는 퍼스트클래스 티켓을 구매한 승객에게만 발송되어야 합니다. 컨텍스트 변수는 이러한 정보를 추적하는 유연한 방법입니다.

사용자는 항공 티켓을 구매할 때 Canvas에 진입합니다. 라운지 이용 자격을 판단하기 위해 컨텍스트 단계에서 lounge_access_granted라는 컨텍스트 변수를 만든 다음, 사용자 여정의 후속 단계에서 해당 컨텍스트 변수를 참조합니다.

이 컨텍스트 단계에서는 {{custom_attribute.${purchased_flight}}}를 사용하여 구매한 항공편 유형이 first_class인지 확인합니다.

다음으로, {{context.${lounge_access_granted}}}가 true인 사용자를 대상으로 하는 메시지 단계를 만듭니다. 이 메시지는 개인화된 라운지 정보가 포함된 푸시 알림입니다. 이 컨텍스트 변수를 기반으로, 자격이 있는 승객은 항공편 전에 관련 메시지를 수신합니다.

• 퍼스트클래스 티켓 승객은 다음 메시지를 수신합니다: “독점 VIP 라운지 이용을 즐기세요!”
• 비즈니스 및 이코노미 티켓 승객은 다음 메시지를 수신합니다: “독점 VIP 라운지 이용을 위해 항공편을 업그레이드하세요.”

팁

컨텍스트 단계의 정보를 활용하여 개인화된 지연 옵션을 추가할 수 있습니다. 즉, 사용자를 지연시키는 변수를 선택할 수 있습니다.

작업 경로 및 종료 기준의 경우

커스텀 이벤트 수행 및 구매하기 트리거 동작에서 속성정보 필터를 컨텍스트 변수 또는 커스텀 속성과 비교하는 기능을 활용할 수 있습니다. 이러한 액션 트리거는 기본 속성정보와 중첩 속성정보 모두에 대한 속성정보 필터를 지원합니다.

• 기본 속성정보와 비교할 때, 사용 가능한 비교 방식은 커스텀 이벤트에서 정의한 속성정보 유형과 일치합니다. 예를 들어, 문자열 속성정보는 정확히 일치, 정규식 일치 등이 있습니다. 불리언 속성정보는 참 또는 거짓입니다.
• 중첩 속성정보와 비교할 때, 유형이 사전 정의되지 않으므로 중첩 커스텀 속성의 비교와 유사하게 불리언, 숫자, 문자열, 시간 및 연중 일자에 대해 여러 데이터 유형에 걸쳐 비교를 선택할 수 있습니다. 비교 시점에 중첩 속성정보의 실제 데이터 유형과 일치하지 않는 데이터 유형을 선택하면, 사용자는 작업 경로 단계 또는 종료 기준에 일치하지 않게 됩니다.

작업 경로 예시

중요

커스텀 속성 비교의 경우, 작업이 수행된 시점의 커스텀 속성 값을 사용합니다. 즉, 비교 시점에 사용자에게 해당 커스텀 속성이 채워져 있지 않거나 커스텀 속성 값이 정의된 속성정보 비교와 일치하지 않으면 사용자는 해당 액션 그룹과 일치하지 않습니다. 사용자가 작업 경로 단계에 진입했을 때 일치했을 경우에도 마찬가지입니다.

• 커스텀 이벤트 수행
• 구매하기

종료 기준 예시

• 커스텀 이벤트 수행
• 구매하기

만료 설정하기

Canvas 메시지 단계의 배너 및 인앱 메시지의 경우, 만료에 대해 단계를 사용할 수 있게 된 후 일정 기간을 선택한 다음, 기간 개인화를 활성화하여 컨텍스트 변수에서 가용 기간을 결정합니다. 예를 들어, 컨텍스트 단계의 프로모션 또는 예약 기간에 맞추는 데 사용할 수 있습니다.

기간 개인화는 해당 기간 기반 만료 옵션에 적용됩니다. 대신 특정 날짜 및 시간에를 선택하면 날짜 및 시간 컨트롤을 사용하여 만료를 설정합니다.

작업 경로 지연

작업 경로 단계의 평가 기간에서 지연 개인화를 활성화하여 컨텍스트 변수에서 사용자가 단계에 머무는 시간을 설정합니다. 등급이나 지역 등의 세부 정보에 따라 사용자별로 대기 시간이 달라야 할 때 사용합니다.

컨텍스트 변수 필터

오디언스 경로 및 결정 분할 단계에서 이전에 선언된 컨텍스트 변수를 사용하는 필터를 만들 수 있습니다.

참고

컨텍스트 변수 필터는 오디언스 경로 및 결정 분할 단계에서만 사용할 수 있습니다.

컨텍스트 변수는 Canvas 범위 내에서 선언되고 접근 가능하므로, Segments에서는 참조할 수 없습니다. 컨텍스트 변수 필터는 오디언스 경로와 결정 분할 단계에서 유사하게 작동합니다. 오디언스 경로 단계는 여러 그룹을 나타내고, 결정 분할 단계는 이진 결정을 나타냅니다.

Canvas 컨텍스트 변수에 사전 정의된 유형이 있는 것과 마찬가지로, 컨텍스트 변수와 정적 값 간의 비교도 일치하는 데이터 유형이어야 합니다. 컨텍스트 변수 필터는 중첩 커스텀 속성의 비교와 유사하게 불리언, 숫자, 문자열, 시간 및 연중 일자에 대해 여러 데이터 유형에 걸쳐 비교를 허용합니다.

다음은 컨텍스트 변수 product_name을 정규식 /braze/와 비교하는 컨텍스트 변수 필터 예시입니다.

날짜 컨텍스트 변수에 대한 연중 일자 및 시간 필터

컨텍스트 변수에 연중 일자 또는 시간 비교 필터를 사용하려면:

1. 컨텍스트 변수를 캘린더 날짜(예: 2025년 10월 23일)로 설정하는 컨텍스트 단계를 추가합니다.
2. 컨텍스트 단계 뒤에 오디언스 경로 단계를 추가합니다.
3. 오디언스 경로 단계에서 해당 컨텍스트 변수를 기준으로 사용자를 분류하는 필터를 추가합니다.
4. 연중 일자 또는 시간 카테고리에서 비교를 선택합니다.

컨텍스트 변수에 선언된 유형이 없으면, Braze는 연중 일자 및 시간을 포함한 모든 사용 가능한 비교 유형을 드롭다운에 표시합니다. 변수가 컨텍스트 단계에서 시간 유형으로 선언된 경우, 연중 일자 및 시간 비교만 표시됩니다. 알려진 유형이 있는 다른 데이터 유형(예: 시간 유형의 중첩 커스텀 속성)의 경우, 해당 유형에 적용되는 비교만 표시됩니다.

참고

컨텍스트 변수와 비교에 동일한 데이터 유형을 사용하세요. 예를 들어, 컨텍스트 변수가 시간 데이터 유형이면 시간 비교(“이전” 또는 “이후” 등)를 사용하세요. 일치하지 않는 데이터 유형(예: 시간 컨텍스트 변수에 문자열 비교)을 사용하면 예상치 못한 동작이 발생할 수 있습니다.

중요

“연중일”과 “시간” 필터 유형 중에서 선택하기: 날짜가 포함된 컨텍스트 변수를 필터링할 때, 날짜가 매년 반복되는지에 따라 올바른 비교 유형을 선택하세요. 컨텍스트 변수가 생성하는 값에 연도가 포함되지 않는 경우에만 “연중일”을 사용하세요.

• “연중일” 사용: 날짜가 매년 반복될 때(예: 생일, 기념일 또는 크리스마스와 같은 휴일). 이 비교 유형은 연도 구성요소를 무시하고 연중일(1-365/366)을 기준으로 계산합니다.
• “시간” 사용: 날짜가 반복되지 않는 절대 날짜일 때(예: 계약 종료일, 약속 날짜 또는 구독 갱신 날짜). 이 비교 유형은 연도를 포함한 전체 타임스탬프를 기준으로 계산합니다.

절대 날짜에 “연중일”을 사용하면 연도 구성요소를 무시하므로 잘못되거나 예상치 못한 결과가 발생할 수 있습니다. 예를 들어, 4월의 미래 계약 종료일이 63일 이내인지 비교할 때, “연중일”을 사용하면 날짜 번호(119 vs 359)만 비교하기 때문에 실제로 4월까지는 188일이 남아 있음에도 잘못 일치할 수 있습니다.

컨텍스트 변수 또는 커스텀 속성과 비교하기

컨텍스트 변수 또는 커스텀 속성과 비교 토글을 선택하면, 이전에 정의된 컨텍스트 변수 또는 사용자 커스텀 속성과 비교하는 컨텍스트 변수 필터를 구성할 수 있습니다. 이는 API 트리거 context와 같이 사용자별로 동적인 비교를 수행하거나, 컨텍스트 변수에 걸쳐 정의된 복잡한 비교 로직을 간소화하는 데 유용할 수 있습니다.

• 예시 1
• 예시 2

시간대 일관성 표준화

타임스탬프 유형을 사용하는 대부분의 이벤트 속성정보는 이미 Canvas에서 UTC로 되어 있지만, 몇 가지 예외가 있습니다. Canvas 컨텍스트가 추가됨에 따라, 행동 기반 Canvases의 모든 기본 타임스탬프 이벤트 속성정보가 일관되게 UTC로 표시됩니다. 이 변경은 캔버스 단계와 메시지를 편집할 때 보다 예측 가능하고 일관된 경험을 보장하기 위한 광범위한 노력의 일환입니다. 이 변경 사항은 특정 Canvas가 컨텍스트 단계를 사용하는지 여부에 관계없이 모든 행동 기반 Canvases에 영향을 미칩니다.

중요

모든 상황에서 타임스탬프가 원하는 시간대로 표시되도록 Liquid time_zone 필터를 사용하는 것을 강력히 권장합니다. 예시는 컨텍스트 단계 문서의 자주 묻는 질문을 참조할 수 있습니다.

관련 문서

• 컨텍스트 단계
• Liquid을 사용한 개인화 및 동적 콘텐츠