API 트리거 Canvas 요청을 Currents 메시징 이벤트에 연결
상관관계 ID를 Canvas 항목 속성으로 전달하고,
message_extras로 전송 이벤트에 기록한 다음,dispatch_id와user_id를 기준으로 인게이지먼트 이벤트를 조인하면 API 트리거 Canvas 요청을 메시징 성과까지 추적할 수 있습니다.
이 예시에 대하여
가상의 금융 서비스 브랜드인 Pyrite Financial은 소비자 트랜잭션에 대한 알림이 필요할 때마다 자체 시스템에서 Canvas를 트리거합니다. 이벤트마다 /canvas/trigger/send를 호출합니다. 분석 팀은 Currents 또는 Snowflake 데이터 공유에서 어떤 트리거 요청이 어떤 전송, 전달, 클릭을 발생시켰는지 알고 싶어 합니다. 두 곳 모두 동일한 메시징 이벤트 데이터를 포함합니다.
Currents와 Snowflake 데이터 공유의 메시징 이벤트에는 트리거 요청 식별자가 자체적으로 포함되지 않습니다. 이 예시에서는 다음 방법을 보여드립니다.
- 전송 시스템에서 상관관계 ID를 생성하고 트리거 요청에 Canvas 항목 속성으로 전달합니다.
- 메시지 본문에서
message_extrasLiquid 태그로 해당 속성을 참조합니다. 이 태그는 값을 전송 이벤트의message_extras필드에 기록합니다. dispatch_id와user_id를 기준으로 전송 이벤트를 전달 및 클릭 이벤트와 조인합니다.
외부 시스템이 트리거를 관리하고 요청별로 다운스트림 인게이지먼트를 보고해야 할 때 이 방법을 사용하세요. 사용 사례에 Canvas보다 Campaign(캠페인)이 더 적합하다면 대신 전송 식별자를 사용하세요. send_id 필드는 Campaign 메시징 엔드포인트에서 지원되며, /canvas/trigger/send에서는 지원되지 않습니다.
고려 사항
dispatch_id만으로는 Canvas의 고유 키가 되지 않습니다. Braze는 캔버스 단계를 트리거된 이벤트로 처리하므로, 단계에 따라 전송별로 사용자마다 고유한dispatch_id가 생성되거나 같은 전송 내 사용자들이dispatch_id를 공유할 수 있습니다. 항상user_id와 함께 사용하세요. 자세한 내용은 디스패치 ID 동작을 참조하세요.message_extras필드는 전송 이벤트에만 표시됩니다. 전달, 열람, 클릭 이벤트에는 포함되지 않으므로 상관관계 ID는 전송 이벤트를 거친 후 다른 이벤트로 조인됩니다.- 메시지 엑스트라는 전송 시점에 메시지별로 첨부되므로, 메시지 단계가 여러 개인 Canvas에서는 보고하려는 각 단계에 태그를 추가해야 합니다.
- 모든
message_extras키와 값을 합쳐 1,000바이트(1 KB) 미만이어야 하며, 이보다 긴 값은 Braze가 잘라냅니다. 공백도 제한에 포함됩니다. - 결과 JSON에는 문자열 값만 포함됩니다. Liquid 변수를 키나 값으로 사용하세요.
message_extras안에 다른 Liquid 태그를 중첩하지 마세요. - Currents 이벤트는 Braze 사용자 ID를
user_id에, 자체 식별자를external_user_id에 저장합니다.user_id를 기준으로 조인하고, 행을 자체 시스템과 매칭해야 할 때는external_user_id를 선택하세요. - 이 패턴에는 Currents 또는 Snowflake 데이터 공유를 사용하세요. 두 가지 모두 전송 이벤트의
message_extras를 포함하여 동일한 메시징 이벤트 필드를 제공합니다. - Currents 및 Snowflake 스키마는
message_extras를 PII로 표시합니다. 소비자 데이터 대신 불투명한 요청 ID를 사용하세요. - Canvas 트리거 요청의
context객체는 최대 50 KB까지 가능하며, 전달하는 모든 속성이 이 용량을 공유합니다.
설정
1단계: 요청별 상관관계 ID 생성
전송 시스템에서 각 트리거 요청에 대한 식별자(예: UUID)를 생성하고 자체 요청 로그에 저장합니다. 불투명하게 유지하고 message_extras 크기 제한에 맞을 만큼 짧게 만드세요.
2단계: ID를 Canvas 항목 속성으로 전달
/canvas/trigger/send 요청의 context 객체에 ID를 포함합니다. 사용자마다 고유한 ID가 있으면 수신자별로 설정하고, 하나의 ID가 요청의 모든 수신자에게 적용되면 최상위 수준에서 설정하세요.
{
"canvas_id": "canvas_identifier",
"recipients": [
{
"external_user_id": "user_identifier",
"context": {
"request_id": "8f14e45f-ceea-467a-9e30-6b1b1c4a7d20"
}
}
]
}
Canvas 항목 속성은 Canvas 전체에서 컨텍스트 변수로 사용할 수 있습니다.
3단계: 전송 이벤트에 ID 기록
보고하려는 각 메시지 단계에서 컨텍스트 변수를 할당하고 message_extras에 전달합니다.
{% assign request_id = context.${request_id} %}
{% message_extras :key request_id :value {{request_id}} %}
Braze는 전송 시점에 키-값 페어를 전송 이벤트의 message_extras 필드에 첨부합니다.
4단계: 테스트 전송으로 확인
Canvas를 통해 테스트 항목을 전송한 다음, Currents 또는 Snowflake 데이터 공유의 전송 이벤트에 request_id 키가 담긴 message_extras가 포함되어 있는지 확인합니다. 필드가 비어 있으면 태그 구문을 확인하세요. 구분 기호 오타나 키와 값의 순서 오류가 흔한 원인입니다.
5단계: 전송을 전달 및 클릭 이벤트와 조인
전송 이벤트에 ID가 기록되면 dispatch_id와 user_id를 기준으로 다른 이벤트와 조인합니다. 다음 쿼리 빌더 예시는 이메일의 요청별 전달 및 클릭 성과를 보고합니다.
WITH sends AS (
SELECT
USER_ID,
EXTERNAL_USER_ID,
DISPATCH_ID,
PARSE_JSON(MESSAGE_EXTRAS):request_id::STRING AS request_id,
TIME AS send_time
FROM USERS_MESSAGES_EMAIL_SEND_SHARED
WHERE MESSAGE_EXTRAS IS NOT NULL
AND PARSE_JSON(MESSAGE_EXTRAS):request_id IS NOT NULL
)
SELECT
s.request_id AS "Request ID",
s.EXTERNAL_USER_ID AS "External User ID",
MIN(s.send_time) AS "Sent",
MIN(d.TIME) AS "Delivered",
MIN(c.TIME) AS "First Click"
FROM sends AS s
LEFT JOIN USERS_MESSAGES_EMAIL_DELIVERY_SHARED AS d
ON d.USER_ID = s.USER_ID
AND d.DISPATCH_ID = s.DISPATCH_ID
LEFT JOIN USERS_MESSAGES_EMAIL_CLICK_SHARED AS c
ON c.USER_ID = s.USER_ID
AND c.DISPATCH_ID = s.DISPATCH_ID
GROUP BY 1, 2
ORDER BY 3 DESC;
전송하는 채널에 맞는 테이블로 바꿔 사용하세요. 예를 들어 푸시의 경우 USERS_MESSAGES_PUSHNOTIFICATION_SEND_SHARED와 USERS_MESSAGES_PUSHNOTIFICATION_OPEN_SHARED를 사용합니다. 테이블별 전체 열 목록은 SQL 테이블 참조를 확인하세요.
쿼리 빌더 예시는 한 가지 방법일 뿐입니다. Snowflake 데이터 공유나 자체 웨어하우스로 내보낸 Currents 데이터에도 동일한 조인을 적용할 수 있습니다. 전송 이벤트의 message_extras를 파싱한 다음, dispatch_id와 user_id를 기준으로 인게이지먼트 이벤트를 조인하세요.