이 페이지는 AI로 자동 번역되었으며 부정확한 내용이 포함될 수 있습니다. 번역 오류를 신고하려면 페이지 오른쪽 목차 아래에 있는 피드백 기능을 사용하세요.

컨텍스트

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

작동 방식

Canvas의 첫 번째 단계로서의 컨텍스트 단계.

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

컨텍스트 변수는 해당 특정 Canvas 여정에서만 존재합니다. 사용자의 프로필을 영구적으로 변경하지 않으며 다른 Canvases에 표시되지도 않습니다. 따라서 특정 Campaign이나 워크플로에만 관련된 임시 정보에 이상적입니다.

팁

데이터 유형, 사용법, 모범 사례를 포함한 컨텍스트 변수의 전체 참조는 컨텍스트 변수 참조를 확인하세요.

컨텍스트 단계 내에서 최대 10개의 컨텍스트 변수를 정의하거나 업데이트할 수 있습니다. 이 변수들은 지연을 개인화하고, 사용자를 동적으로 세분화하며, Canvas 전체에서 메시징을 강화하는 데 사용할 수 있습니다. 예를 들어, 사용자의 예정된 항공편 시간에 대한 컨텍스트 변수를 생성한 다음, 이를 사용하여 개인화된 지연을 설정하고 리마인더를 보낼 수 있습니다.

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

Canvas 진입 시: 커스텀 이벤트 또는 API 트리거의 속성정보가 자동으로 컨텍스트 변수로 채워집니다.
컨텍스트 단계에서: 컨텍스트 단계를 추가하여 컨텍스트 변수를 수동으로 정의하거나 업데이트합니다.

각 컨텍스트 변수에는 이름, 데이터 유형, 값(Liquid 또는 개인화 추가 도구를 사용하여 설정)이 필요합니다. 정의한 후에는 {{context.${flight_time}}}와 같은 Liquid를 사용하여 Canvas 전체에서 컨텍스트 변수를 참조할 수 있습니다. 컨텍스트 변수 이름 필드에서 컨텍스트 변수 이름을 직접 입력하거나 단계 편집기의 드롭다운에서 선택할 수도 있습니다. 자세한 내용은 컨텍스트 변수 참조를 확인하세요.

각 Canvas 진입 시 최신 진입 데이터 및 Canvas 설정에 따라 컨텍스트 변수가 재정의되므로, 사용자는 각각 고유한 컨텍스트를 가진 여러 활성 여정을 동시에 진행할 수 있습니다. 예를 들어, 고객에게 예정된 항공편이 두 개 있다면, 각 항공편에 대해 출발 시간과 목적지 같은 항공편별 컨텍스트 변수를 가진 두 개의 별도 여정 상태가 동시에 실행됩니다. 이를 통해 오후 2시 뉴욕행 항공편에 대한 개인화된 리마인더를 보내는 동시에, 내일 오전 8시 로스앤젤레스행 항공편에 대한 다른 업데이트를 보낼 수 있어 각 메시지가 해당 예약에 적합하게 유지됩니다.

사용자 처리 및 배치

컨텍스트 단계는 성능 최적화를 위해 사용자를 배치로 처리합니다. 사용자가 컨텍스트 단계에 진입하면 Braze는 기본적으로 1,000명 단위의 배치로 처리합니다. 이 배치들은 병렬로 처리되지만, 각 배치 내에서 사용자는 순차적으로 처리됩니다.

이것이 의미하는 바는 다음과 같습니다:

예시: 3,500명의 사용자가 사용자당 650ms가 걸리는 연결된 콘텐츠가 포함된 컨텍스트 단계에 진입하는 경우:

Braze는 4개의 사용자 배치를 생성합니다(이 예시에서는 1,000명, 1,000명, 1,000명, 500명).
각 배치는 사용자를 순차적으로 처리하므로, 1,000명의 배치는 약 10.8분(650초; 1,000 × 650ms)이 소요됩니다.
배치마다 완료 시간이 다르므로, 각 배치가 완료됨에 따라 사용자가 점진적으로 다음 단계로 이동합니다.
첫 번째 사용자는 배치 크기와 연결된 콘텐츠 응답 시간에 따라 마지막 사용자보다 몇 분 먼저 다음 단계에 도달할 수 있습니다.

연결된 콘텐츠가 없으면 외부 API 호출을 기다릴 필요가 없으므로 컨텍스트 단계가 훨씬 빠르게 처리됩니다.

고려 사항

Context 단계당 최대 10개의 컨텍스트 변수를 정의할 수 있습니다.
각 변수에는 고유한 이름이 필요합니다(문자, 숫자, 밑줄만 사용 가능, 최대 100자).
한 단계의 모든 변수 총 크기는 50KB를 초과할 수 없습니다.
API 트리거를 통해 전달된 변수는 Context 단계에서 생성된 변수와 동일한 네임스페이스를 공유합니다. Context 단계에서 변수를 재정의하면 API 값이 덮어쓰기됩니다.

자세한 내용과 고급 사용법은 컨텍스트 변수 참조를 확인하세요.

컨텍스트 단계 만들기

팁

오디언스 경로 또는 결정 분할 단계에서 트리거 이벤트의 속성을 참조하기 위해 Context 단계가 필요하지 않습니다. Context Variable 필터를 사용하여 필터 그룹에서 속성을 직접 참조할 수 있습니다. 올바른 데이터 유형을 선택해야 합니다.

1단계: 단계 추가하기

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

2단계: 변수 정의하기

참고

각 컨텍스트 단계에서 최대 10개의 컨텍스트 변수를 정의할 수 있습니다.

컨텍스트 변수를 정의하려면 다음을 수행합니다:

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

이제 메시지 및 사용자 업데이트 단계 등 Liquid를 사용하는 모든 곳에서 개인화 추가를 선택하여 컨텍스트 변수를 사용할 수 있습니다. 컨텍스트 변수 이름 필드에서 컨텍스트 변수 이름을 직접 입력하거나 단계 편집기의 드롭다운에서 선택할 수도 있습니다. 전체 안내는 컨텍스트 변수 레퍼런스를 참조하세요.

중요

컨텍스트 변수를 참조할 때는 항상 {{context.${variable_name}}} 형식을 사용하세요.

컨텍스트 변수 필터

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

에이전트 단계 응답을 기반으로 사용자를 라우팅하려면 오디언스 경로 또는 결정 분할 단계 앞에 에이전트 단계를 추가하세요. 에이전트 단계는 출력을 Canvas 컨텍스트에 저장하며, 해당 분기 단계에서 컨텍스트 변수 필터를 사용하여 이를 평가할 수 있습니다.

에이전트가 객체를 반환하고 중첩된 속성정보를 기준으로 필터링하려면 컨텍스트 변수 이름 필드에 최상위 변수 이름만 입력하는 대신 점 표기법을 사용하여 경로를 입력합니다(예: persona가 intent_agent 아래에 중첩된 경우 intent_agent.persona).

필터 설정, 비교 로직 및 고급 예제에 대한 자세한 내용은 컨텍스트 변수 레퍼런스를 참조하세요.

중요

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

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

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

사용자 경로 미리보기

메시지가 올바른 오디언스에게 전송되고 컨텍스트 변수가 예상 성과로 평가되는지 확인하기 위해 사용자 경로를 미리보기하여 테스트하는 것을 권장합니다.

참고

편집기의 미리보기 및 테스트 전송 섹션에서 Canvas를 미리보는 경우, 이 패널은 미리보기를 문자열로 생성하기 때문에 테스트 메시지 미리보기의 타임스탬프가 UTC로 표준화되지 않습니다. 즉, Canvas가 time 객체를 수신하도록 설정된 경우, 메시지 미리보기는 Canvas가 실시간으로 실행될 때 발생하는 결과를 정확하게 미리 보여주지 않습니다. Canvas를 가장 정확하게 테스트하려면 대신 사용자 경로를 미리보기하는 것을 권장합니다.

잘못된 컨텍스트 변수를 생성하는 일반적인 시나리오를 반드시 확인하세요. 사용자 경로를 미리볼 때, 컨텍스트 변수를 사용하는 개인화된 지연 단계의 성과와 사용자를 컨텍스트 변수에 매칭하는 오디언스 또는 결정 분할 단계의 비교 결과를 확인할 수 있습니다.

컨텍스트 변수가 유효한 경우, Canvas 전체에서 해당 변수를 참조할 수 있습니다. 그러나 컨텍스트 변수가 올바르게 생성되지 않으면 Canvas의 이후 단계도 올바르게 수행되지 않습니다. 예를 들어, 컨텍스트 단계를 생성하여 사용자에게 예약 시간을 할당하고 예약 시간의 값을 과거 날짜로 설정하면 메시지 단계의 알림 이메일이 전송되지 않습니다.

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

Context 단계에서 연결된 콘텐츠 호출을 수행할 때, 호출에서 반환된 JSON은 일관성과 오류 방지를 위해 문자열 데이터 유형으로 평가됩니다. 이 문자열을 JSON으로 변환하려면 as_json_string을 사용하여 변환하세요. 예시:

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

문제 해결

유효하지 않은 컨텍스트 변수

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

임베디드 연결된 콘텐츠 호출이 실패한 경우
Liquid 표현식이 런타임에 데이터 유형과 일치하지 않는 값을 반환하거나 빈 값(null)을 반환하는 경우
Liquid 표현식이 {% abort_message() %}를 호출하는 경우

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

이러한 상황에서는:

사용자가 다음 단계로 진행합니다.
Canvas 단계 분석에서 이를 _업데이트되지 않음_으로 집계합니다.

문제 해결 시 업데이트되지 않음 지표를 모니터링하여 컨텍스트 변수가 올바르게 업데이트되고 있는지 확인하세요. 컨텍스트 변수가 유효하지 않으면 사용자는 컨텍스트 단계를 지나 Canvas에서 계속 진행할 수 있지만, 이후 단계에 적합하지 않을 수 있습니다.

각 데이터 유형의 설정 예시는 데이터 유형을 참조하세요.

컨텍스트 변수는 abort_message를 사용하여 의도적으로 건너뛸 수도 있습니다. 컨텍스트 변수에서 abort_message 사용하기를 참조하세요.

컨텍스트 변수에서 `abort_message` 사용하기

컨텍스트 변수의 값에 abort_message Liquid 태그를 사용하여 일부 사용자에 대해 해당 변수를 건너뛸 수 있습니다. 컨텍스트 단계에서 abort_message는 해당 변수에만 영향을 미칩니다. 단계를 중단하지 않으며, 사용자를 Canvas에서 퇴장시키지도 않습니다.

컨텍스트 변수의 Liquid가 특정 사용자에 대해 abort_message를 호출하면:

해당 사용자에 대해 변수가 설정되지 않습니다. 이전 컨텍스트 단계에서 이미 이 변수를 설정한 경우, 사용자는 이전 값을 유지합니다.
해당 단계의 다른 변수는 여전히 평가되고 설정됩니다.
동일한 단계에서 이 변수를 참조하는 이후 변수는 해당 변수로부터 새 값을 받지 못합니다.
사용자가 다음 단계로 진행합니다.
Canvas 단계 분석에서 해당 변수를 _업데이트되지 않음_으로 집계합니다.

예를 들어, 다음 변수는 프랑스에 있는 사용자에 대해 true로 설정되고 그 외 모든 사용자에 대해서는 건너뜁니다:

{% if ${country} == "France" %}
  true
{% else %}
  {% abort_message("Not in France") %}
{% endif %}

사용자 경로를 미리보기할 때, 건너뛴 변수는 “Liquid 로직이 중단을 트리거했기 때문에 variable_name이(가) 업데이트되지 않았습니다”로 표시됩니다.

이후 단계가 이 변수에 의존하는 경우, 변수가 설정되지 않은 사용자를 위한 계획을 세우세요. 예를 들어, 오디언스 경로 단계를 사용하여 해당 사용자를 라우팅할 수 있습니다.

참고

컨텍스트 단계 중단은 메시지 활동 로그에 기록되지 않으며, abort_message에 전달한 사유도 표시되지 않습니다.

연결된 콘텐츠를 사용한 전송 지연

배치 내의 모든 사용자가 처리된 후에야 사용자가 진행됩니다. 배치 처리가 완료되면, 성공한 사용자는 다음 단계로 이동하고 실패한 사용자는 별도로 재시도됩니다. 성공한 사용자는 재시도가 성공할 때까지 기다리지 않고 바로 진행합니다.

재시도 동작

Canvas에서 연결된 콘텐츠 호출은 해당 호출에 :retry가 포함된 경우에만 재시도됩니다.

컨텍스트 및 사용자 업데이트 단계: Braze는 단계 수준에서 연결된 콘텐츠 호출을 재시도합니다(최대 5회). 모든 재시도가 실패하면 사용자는 Canvas에서 퇴장합니다.
메시지 단계: :retry가 포함된 연결된 콘텐츠는 여전히 메시징 파이프라인을 사용합니다. 수신자는 Braze가 최대 5회 호출을 재시도하는 동안 전송 대기줄에서 지연됩니다. 모든 재시도가 실패하면 메시지가 중단되고 사용자는 다음 단계로 진행합니다.

컨텍스트 및 사용자 업데이트 단계의 경우, 프로모 코드 가져오기 실패나 예기치 않은 단계 오류와 같은 특정 재시도 가능한 단계 오류는 Braze가 사용자를 Canvas에서 퇴장시키기 전에 지수 백오프를 사용한 추가 단계 수준 재시도(약 13회)를 트리거할 수 있습니다.

:retry 태그에 대한 자세한 내용은 연결된 콘텐츠 재시도를 참조하세요.

컨텍스트 단계를 통해 모든 사용자를 처리하는 데 걸리는 시간은 다음에 따라 달라집니다:

단계에 진입하는 사용자 수
연결된 콘텐츠 사용 여부(및 응답 시간)
배치 크기(기본값 배치당 1,000명)

연결된 콘텐츠 엔드포인트에 사용량 제한이 있는 경우, 컨텍스트 단계는 각 배치 내에서 사용자를 순차적으로 처리하므로 사용량 제한을 자연스럽게 준수하는 데 도움이 된다는 점을 고려하세요. 그러나 여러 배치가 병렬로 처리되므로, 엔드포인트가 여러 배치의 동시 요청을 처리할 수 있는지 확인하세요.

시간대 일관성 표준화

Canvas 컨텍스트가 정식 출시됨에 따라, 액션 기반 Canvases의 모든 기본 타임스탬프 이벤트 속성정보는 UTC로 표시됩니다. 이 변경은 캔버스 단계와 메시지를 편집할 때 보다 예측 가능하고 일관된 경험을 보장하기 위한 노력의 일환입니다. 이 변경은 특정 Canvas가 컨텍스트 단계를 사용하는지 여부에 관계없이 모든 액션 기반 Canvases에 적용됩니다.

중요

모든 상황에서, 타임스탬프가 원하는 시간대로 표시되도록 Liquid time_zone 필터를 사용하는 것을 강력히 권장합니다. 예시는 이 자주 묻는 질문을 참조하세요.

자주 묻는 질문

Canvas 컨텍스트가 정식 출시된 이후 무엇이 변경되었나요?

Canvas 컨텍스트가 정식 출시됨에 따라 다음 세부 사항이 적용됩니다:

액션 기반 Canvases의 트리거 이벤트 속성정보에서 datetime 유형을 가진 모든 타임스탬프는 UTC로 표시됩니다.
이 변경 사항은 특정 Canvas가 컨텍스트 단계를 사용하고 있는지 여부와 관계없이 모든 액션 기반 Canvases에 영향을 미칩니다.

이 변경의 이유는 무엇인가요?

이 변경은 캔버스 단계와 메시지를 편집할 때 보다 예측 가능하고 일관된 경험을 제공하기 위한 광범위한 노력의 일환입니다.

API 트리거 또는 스케줄된 Canvases도 이 변경의 영향을 받나요?

아니요.

이 변경이 Canvas 진입 속성정보에 영향을 미치나요?

네, 액션 기반 Canvas에서 canvas_entry_property가 사용되고 있고 속성정보 유형이 time인 경우 canvas_entry_properties에 영향을 미칩니다. 모든 상황에서 타임스탬프가 원하는 시간대로 표시되도록 Liquid time_zone 필터를 사용하는 것을 권장합니다.

다음은 이를 수행하는 방법의 예시입니다:

메시지 단계의 Liquid	출력	Liquid에서 시간대를 올바르게 표현하는 방법인가요?
`{{canvas_entry_properties.${timestamp_property}}}`	`2025-08-05T08:15:30:250-0800`	아니요
`{{canvas_entry_properties.${timestamp_property} \| date: "%Y-%m-%d %l:%M %p"}}`	`2025-08-05 4:15pm`	아니요
`{{canvas_entry_properties.${timestamp_property} \| time_zone: "America/Los_Angeles" \| date: "%Y-%m-%d %l:%M %p"}}`	`2025-08-05 8:15am`	네

새로운 타임스탬프 동작이 메시지에 어떤 영향을 미칠 수 있는지 실제 예시는 무엇인가요?

메시지 단계에 다음 내용이 포함된 액션 기반 Canvas가 있다고 가정해 보겠습니다:

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

이 경우 다음과 같은 메시지가 생성됩니다:

Your appointment is scheduled for 2025-08-05 4:15 PM, we’ll see you then!

Liquid를 사용하여 시간대가 지정되지 않았으므로 여기서 타임스탬프는 UTC입니다.

시간대를 명확하게 지정하려면 다음과 같이 Liquid time_zone 필터를 사용할 수 있습니다:

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!