컨텍스트

컨텍스트 단계를 사용하면 사용자가 캔버스를 이동할 때 하나 이상의 변수를 생성하고 업데이트할 수 있습니다. 예를 들어 시즌별 할인을 관리하는 캔버스가 있는 경우 컨텍스트 변수를 사용하여 사용자가 캔버스에 들어올 때마다 다른 할인 코드를 저장할 수 있습니다.

작동 방식

캔버스의 첫 번째 단계인 컨텍스트 단계.](/docs/ko/assets/img/context_step3.png?fa6617cfab3adb369b499fdc7aa9d553){: style=”float:right;max-width:40%;margin-left:15px;”}

컨텍스트 단계를 사용하면 사용자가 특정 캔버스를 통과하는 동안 임시 데이터를 생성하고 사용할 수 있습니다. 이 데이터는 해당 캔버스 여정 내에서만 존재하며 다른 캔버스나 세션 외부에 지속되지 않습니다.

이 프레임워크 내에서 각 컨텍스트 단계는 사용자의 프로필 정보를 영구적으로 변경하지 않고도 지연을 개인화하고, 사용자를 동적으로 세분화하고, 메시징을 강화할 수 있는 임시 데이터 조각인 여러 컨텍스트 변수를 정의할 수 있습니다.

예를 들어 항공편 예약을 관리하는 경우 각 사용자의 예정된 비행 시간에 대한 컨텍스트 변수를 만들 수 있습니다. 그런 다음 각 사용자의 비행 시간을 기준으로 지연을 설정하고 동일한 캔버스에서 개인화된 알림을 보낼 수 있습니다.

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

• 캔버스 항목에서: 사용자가 캔버스에 들어가면 이벤트 또는 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}} 로 참조할 수 있으며, 캔버스의 컨텍스트 단계에서 해당 변수를 다시 선언하면 이전에 보낸 내용을 재정의할 수 있습니다.
• 컨텍스트 단계당 최대 50KB까지 저장할 수 있으며, 단계당 최대 10개의 변수를 분산하여 저장할 수 있습니다. 한 단계에서 50KB를 초과하는 변수 크기는 사용자를 위해 평가되거나 저장되지 않습니다. 이러한 크기는 순차적으로 계산됩니다. 예를 들어 컨텍스트 단계에 3개의 변수가 있는 경우입니다:
  • 변수 1: 30 KB
  • 변수 2: 19 KB
  • 변수 3: 2 KB
  • 즉, 변수 3은 다른 모든 컨텍스트 변수의 합이 50KB를 초과하기 때문에 평가되거나 저장되지 않습니다.

컨텍스트 만들기 단계

1단계: 단계 추가

캔버스에 단계를 추가한 다음 사이드바에서 컴포넌트를 드래그 앤 드롭하거나 더하기 버튼을 선택하고 컨텍스트를 선택합니다.

2단계: 변수 정의

컨텍스트 변수를 정의합니다:

1. 컨텍스트 변수에 이름을 지정합니다.
2. 데이터 유형을 선택합니다.
3. Liquid 표현식을 직접 작성하거나 개인화 추가를 사용하여 기존 속성에서 Liquid 스니펫을 생성하세요.
4. 미리 보기를 선택하여 컨텍스트 변수 값을 확인합니다.
5. (선택 사항) 변수를 추가하려면 컨텍스트 변수 추가를 선택하고 1~4단계를 반복합니다.
6. 완료했으면 완료를 선택합니다.

이제 메시지 및 사용자 업데이트 단계 등 Liquid를 사용하는 모든 곳에서 개인화 추가를 선택하여 컨텍스트 변수를 사용할 수 있습니다. 전체 안내는 컨텍스트 변수 사용하기를 참조하세요.

컨텍스트 변수 데이터 유형

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

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

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

컨텍스트 변수 사용

예를 들어, 승객에게 다가오는 항공편 전에 VIP 라운지 이용에 대해 알리고 싶다고 가정해 보겠습니다. 이 메시지는 일등석 항공권을 구매한 승객에게만 전송해야 합니다. 컨텍스트 변수는 이 정보를 추적하는 유연한 방법입니다.

사용자는 비행기 티켓을 구매할 때 캔버스에 입장하게 됩니다. 라운지 이용 자격을 결정하기 위해 컨텍스트 단계에서 lounge_access_granted 이라는 컨텍스트 변수를 만든 다음, 사용자 여정의 후속 단계에서 해당 컨텍스트 변수를 참조합니다.

!승객이 VIP 라운지 이용 자격이 있는지 추적하도록 설정된 컨텍스트 변수입니다.

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

다음으로 {{context.${lounge_access_granted}}} 이 true 인 사용자를 타겟팅하는 메시지 단계를 만들어 보겠습니다. 이 메시지는 개인화된 라운지 정보가 포함된 푸시 알림으로 전송됩니다. 이 컨텍스트 변수를 기반으로 해당 승객은 비행 전에 관련 메시지를 받게 됩니다.

• 일등석 항공권 승객에게는 다음과 같은 혜택이 제공됩니다: “VIP 전용 라운지를 이용하세요!”
• 비즈니스 및 이코노미 항공권 승객에게 제공됩니다: “항공편을 업그레이드하여 VIP 전용 라운지를 이용하세요.”

구매한 항공권 유형에 따라 전송할 메시징이 다른 메시지 단계입니다.](/docs/ko/assets/img/context_example3.png?e77c583305de52bab873505ba00d71ae){: style=”max-width:90%”}

행동 경로 및 종료 기준의 경우

이러한 트리거 동작에서 컨텍스트 변수 또는 커스텀 속성과 속성 필터를 비교하여 활용할 수 있습니다: 커스텀 이벤트 진행 및 구매하기. 이러한 동작 트리거는 기본 및 중첩 프로퍼티 모두에 대한 프로퍼티 필터도 지원합니다.

• 기본 속성과 비교할 때 사용 가능한 비교는 커스텀 이벤트에 정의된 속성 유형과 일치합니다. 예를 들어 문자열 속성은 정확히 동일한 정규식 일치를 갖습니다. 부울 속성은 참 또는 거짓입니다.
• 중첩된 속성을 비교할 때는 유형이 미리 정의되지 않으므로 중첩된 고객 속성을 비교할 때와 마찬가지로 부울, 숫자, 문자열, 시간 및 요일에 대해 여러 데이터 유형에 걸쳐 비교를 선택할 수 있습니다. 비교 시점에 중첩된 속성의 실제 데이터 유형과 일치하지 않는 데이터 유형을 선택하면 사용자는 행동 경로 또는 종료 기준과 일치하지 않게 됩니다.

행동 경로 예시

• perform custom event
• make purchase

종료 기준 예시

• perform custom event
• make purchase

컨텍스트 변수 필터

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

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

컨텍스트 변수가 있는 필터를 만드는 옵션이 있는 결정 분할 단계 예제입니다.](/docs/ko/assets/img/context_decision_split.png?2b0b9149335a2ac917d26eadd79d37c4){: style=”max-width:90%;”}

캔버스 컨텍스트 변수에 사전 정의된 유형이 있는 것과 마찬가지로, 컨텍스트 변수와 정적 값 간의 비교에는 일치하는 데이터 유형이 있어야 합니다. 컨텍스트 변수 필터를 사용하면 중첩된 고객 속성의 비교와 마찬가지로 부울, 숫자, 문자열, 시간, 요일 등 여러 데이터 유형에 대한 비교를 수행할 수 있습니다.

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

컨텍스트 변수 “product_name” 에 대한 필터 설정이 정규식 “/braze/”와 일치하도록 합니다.](/docs/ko/assets/img/context_variable_filter1.png?b3ce74477d77ff73dacab0b44eeab023){: style=”max-width:90%;”}

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

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

• example 1
• example 2

사용자 경로 미리보기

사용자 경로를 테스트하고 미리 확인하여 메시지가 올바른 오디언스에게 전송되고 컨텍스트 변수가 예상 결과에 맞게 평가되는지 확인하는 것이 좋습니다.

잘못된 컨텍스트 변수를 생성하는 일반적인 시나리오를 관찰하세요. 사용자 경로를 미리 볼 때 컨텍스트 변수를 사용하여 개인화된 지연 단계의 결과와 사용자를 컨텍스트 변수와 일치시키는 모든 대상, 의사 결정 또는 행동 경로 단계 비교를 볼 수 있습니다.

컨텍스트 변수가 유효하면 캔버스 전체에서 해당 변수를 참조할 수 있습니다. 그러나 컨텍스트 변수가 올바르게 생성되지 않은 경우 캔버스의 향후 단계도 올바르게 수행되지 않습니다. 예를 들어 사용자에게 약속 시간을 할당하는 컨텍스트 단계를 만들지만 약속 시간의 값을 과거 날짜로 설정하면 메시지 단계의 리마인더 이메일이 전송되지 않습니다.

연결된 콘텐츠 문자열을 JSON으로 변환하기

컨텍스트 단계에서 연결된 콘텐츠를 호출할 때 일관성 및 오류 방지를 위해 호출에서 반환되는 JSON은 문자열 데이터 유형으로 평가됩니다. 이 문자열을 JSON으로 변환하려면 as_json_string 을 사용하여 변환합니다. 예를 들어

1
2
{% connected_content http://example.com :save product %}
{{ product | as_json_string }}

시간대 일관성 표준화

캔버스 컨텍스트가 추가되면 동작 기반 캔버스의 트리거 이벤트 속성정보에서 날짜/시간 유형을 가진 모든 타임스탬프가 항상 UTC로 정규화됩니다. 이전에는 이벤트 속성정보의 타임스탬프가 일부 예외를 제외하고 UTC로 정규화되었습니다. 이제 캔버스 단계와 메시지를 편집할 때 보다 일관된 경험을 제공할 수 있습니다.

이 변경 사항이 캔버스의 타임스탬프에 어떤 영향을 미치는지 이 예시를 살펴보세요. 캔버스의 첫 번째 단계에서 이벤트 속성정보를 사용하는 액션 기반 캔버스와 다음 메시지 단계가 있다고 가정해 보겠습니다:

Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

메시지 단계를 첫 번째 단계로 하는 컨텍스트 여정.](/docs/ko/assets/img/context_timezone_example.png?1c9dbf77ef4fc87a4133f7470b7cbbb4){: style=”max-width:50%”}

이 단계에는 다음과 같은 이벤트 페이로드도 포함됩니다:

1
2
3
{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
}

지금까지의 메시지는 다음과 같습니다: Your appointment is scheduled for 2025-08-05 8:15am, we'll see you then!

캔버스 컨텍스트 얼리 액세스를 통해 이제 메시징이 제공됩니다: Your appointment is scheduled for 2025-08-05 4:15pm, we’ll see you then! 이는 타임스탬프가 태평양 표준시( -08:00)로 원래 페이로드에 지정된 시간대보다 8시간 빠른 UTC로 되어 있기 때문입니다.

Liquid를 사용하여 원하는 시간대의 타임스탬프 표시하기

다음 Liquid 스니펫을 고려하세요:

1
Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | time_zone: "America/Los_Angeles" | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

이 로직은 다음과 같은 출력을 생성합니다: Your appointment is scheduled for 2025-08-05 8:15am, we'll see you then!

선호하는 시간대는 이벤트 속성정보 페이로드에 전송되어 Liquid 로직에서 사용될 수도 있습니다:

1
2
3
4
{
  "appointment_time": "2025-08-05T08:15:30:250-0800"
  "user_timezone": "America/Los_Angeles"
}

Liquid 스니펫의 예시입니다:

1
Your appointment is scheduled for {{canvas_entry_properties.${appointment_time} | time_zone: canvas_entry_properties.${user_timezone} | date: "%Y-%m-%d %l:%M %p"}}, we'll see you then!

문제 해결

잘못된 컨텍스트 변수

컨텍스트 변수는 다음과 같은 경우 유효하지 않은 것으로 간주됩니다:

• 임베드된 연결된 콘텐츠에 대한 호출이 실패했습니다.
• 런타임에 Liquid 표현식은 데이터 유형과 일치하지 않거나 비어 있는 값(null)을 반환합니다.

예를 들어 컨텍스트 변수 데이터 유형이 숫자이지만 Liquid 표현식이 문자열을 반환하는 경우 유효하지 않습니다.

이런 상황에서는

• 사용자는 다음 단계로 진행됩니다.
• 캔버스 단계 분석에서는 이를 업데이트되지 않음으로 계산합니다.

문제 해결 시 업데이트되지 않음 측정기준을 모니터링하여 컨텍스트 변수가 올바르게 업데이트되고 있는지 확인하세요. 컨텍스트 변수가 유효하지 않은 경우 사용자는 컨텍스트 단계를 지나 캔버스에서 계속 진행할 수 있지만 이후 단계에 대한 자격을 얻지 못할 수 있습니다.

각 데이터 유형에 대한 설정 예는 컨텍스트 변수 데이터 유형을 참조하세요.

자주 묻는 질문

컨텍스트 변수는 캔버스 항목 프로퍼티와 어떻게 다릅니까?

컨텍스트 단계 얼리 액세스에 참여 중인 경우 이제 캔버스 항목 속성이 캔버스 컨텍스트 변수로 포함됩니다. 즉, Liquid 스니펫에서 컨텍스트 변수를 사용하는 것과 유사하게 Braze API를 사용하여 캔버스 항목 속성을 전송하고 다른 단계에서 이를 참조할 수 있습니다.

변수가 Singular Context 단계에서 서로 참조할 수 있나요?

예. 컨텍스트 단계의 모든 변수는 순서대로 평가되므로 다음과 같은 컨텍스트 변수를 설정할 수 있습니다:

이는 여러 컨텍스트 단계에도 적용됩니다. 예를 들어 다음 시퀀스를 상상해 보세요:

1. 초기 컨텍스트 단계는 job_title 값으로 JobInfo 라는 변수를 만듭니다.
2. 메시지 단계는 {{context.${JobInfo}}} 을 참조하고 사용자에게 job_title 을 표시합니다.
3. 나중에 컨텍스트 단계에서 컨텍스트 변수를 업데이트하여 JobInfo 의 값을 job_description 으로 변경합니다.
4. JobInfo 을 참조하는 모든 후속 단계는 이제 업데이트된 값 job_description 을 사용합니다.

컨텍스트 변수는 캔버스 전체에서 가장 최근 값을 사용하며, 각 업데이트는 해당 변수를 참조하는 모든 다음 단계에 영향을 미칩니다.

캔버스 컨텍스트 시간대 일관성 표준화가 API 트리거 캔버스에 영향을 주나요?

아니요, 이 변경 사항은 동작이 트리거된 캔버스에만 영향을 줍니다. API 트리거 캔버스로 전송되는 타임스탬프는 시간 유형이 아닌 문자열 유형을 사용하므로 원래 시간대가 항상 유지됩니다.

이것은 캔버스 항목 속성 및 이벤트 속성정보에 명시된 예외와 어떤 관련이 있나요?

캔버스 컨텍스트 얼리 액세스에 참여하면 캔버스 컨텍스트 단계를 사용하는지 여부에 관계없이 이러한 예외가 제거됩니다.