연결된 콘텐츠 디버거

연결된 콘텐츠 디버거를 사용하면 각 연결된 콘텐츠 호출에 대한 실시간 요청 및 응답을 확인할 수 있으므로, Campaign 또는 Canvas를 시작하기 전에 엔드포인트, 헤더, Liquid 태그를 검증할 수 있습니다.

디버거 정보

연결된 콘텐츠를 사용하면 렌더링 시점에 외부 API로 HTTP 호출을 보내고, 그 응답을 Liquid로 메시지에 삽입하여 실시간 데이터로 메시지를 풍부하게 만들 수 있습니다. 이 호출은 Braze 외부에서 이루어지기 때문에 Campaign이나 Canvas가 실시간으로 전환되기 전에는 Braze가 어떤 요청을 보냈는지, 엔드포인트가 무엇을 반환했는지, 또는 호출이 왜 실패했는지 정확히 확인하기 어려울 수 있습니다.

연결된 콘텐츠 디버거는 출시 전에 이러한 문제를 해결하는 데 도움을 줍니다. 미리보기 및 테스트 섹션에서 메시지에 포함된 모든 연결된 콘텐츠 호출의 실시간 요청과 응답을 보여줍니다. 이를 통해 Braze 대시보드 안에서 엔드포인트, 헤더, Liquid 태그가 올바르게 구성되었는지 확인할 수 있습니다.

지원 영역

연결된 콘텐츠 디버거는 다음 영역에서 사용할 수 있습니다.

• 배너
• 캔버스 컨텍스트 단계
• Content Blocks
• Content Cards
• 이메일
  • 템플릿 포함
  • 푸터 및 가입 페이지 제외
• 인앱 메시지
• 푸시 알림
• SMS, MMS 및 RCS
• 웹훅
  • 템플릿 포함
• WhatsApp

디버거 사용

미리보기를 실행할 때마다 Braze는 연결된 콘텐츠 호출 결과를 미리보기 탭에 자동으로 렌더링합니다. 디버거를 사용하려면 다음 단계를 따르세요.

1. {% connected_content %} 태그로 메시지를 구성합니다.
2. 미리보기 및 테스트 섹션으로 이동합니다. 메시지에 연결된 콘텐츠 태그가 포함되어 있으면 연결된 콘텐츠 호출 수와 성공 및 오류 상태를 보여주는 요약 보기를 확인할 수 있습니다.

3. 세부 정보 보기를 선택하면 미리보기 옆에 디버거가 열립니다. 이 창에는 각 연결된 콘텐츠 호출의 URL과 성과가 표로 표시됩니다.

4. 각 URL과 성과 옆에 있는 보기를 선택하면 요청 및 응답 헤더, 페이로드, 메서드, 소요 시간, 캐싱 정보를 확인할 수 있습니다.

5. 결과를 검토하고 필요에 따라 태그, 헤더 또는 엔드포인트를 조정합니다. 그런 다음 새 미리보기를 생성하여 수정 사항을 확인합니다.

템플릿에 {% connected_content %} 태그가 두 개 이상 포함되어 있으면 디버거는 실행된 모든 호출을 나열합니다. 하나의 템플릿에서 여러 메시지 본문이나 플랫폼 배리언트를 렌더링하는 채널의 경우, 디버거는 현재 미리보기 중인 본문뿐만 아니라 해당 렌더링 전체에서 발생한 모든 연결된 콘텐츠 호출을 나열합니다. 이메일은 HTML과 일반 텍스트 렌더링을 별도로 수행할 수 있으며(발송 시에는 가속 모바일 페이지(AMP)도 포함), 따라서 동일한 URL이 두 번 이상 표시될 수 있습니다. 빠른 푸시(Quick Push)는 최대 네 개의 플랫폼(iOS, Android, 웹, Kindle)에 대해 렌더링될 수 있으므로 동일한 연결된 콘텐츠 참조가 최대 네 번까지 표시될 수 있습니다.

이러한 반복은 Braze가 메시지를 렌더링하고 발송하는 방식과 일치하며, 디버거는 이를 하나로 합치지 않습니다. 호출량이 발송 수를 초과할 수 있는 이유에 대한 자세한 내용은 연결된 콘텐츠 호출량 이해하기를 참조하세요.

디버그 출력 이해하기

각 연결된 콘텐츠 호출에는 자체 응답 탭과 요청 탭이 표시됩니다. 응답 탭은 호출 성공 여부를 가장 먼저 확인할 수 있는 지표이므로 기본으로 표시됩니다.

URL 세부 정보

필드	설명
URL	Liquid 태그가 모두 처리된 상태로 Braze가 호출한 최종 렌더링 URL입니다.
메서드	사용된 HTTP 메서드(GET 또는 POST)입니다.
상태 코드	엔드포인트가 반환한 HTTP 상태 코드입니다(예: 200, 404, 500). Braze 전용 코드는 응답 코드 문제 해결을 참조하세요.

응답 탭

필드	설명
소요 시간	요청이 완료되기까지 걸린 시간(초)입니다. 소요 시간은 실시간(캐시되지 않은) 호출에만 표시됩니다.
캐시에서 제공됨	이 응답이 엔드포인트에 대한 실시간 호출이 아니라 Braze의 연결된 콘텐츠 캐시에서 제공되었는지 여부를 나타냅니다(예 또는 아니요). 캐시된 결과는 이전 응답을 반영하므로 엔드포인트의 현재 상태와 다를 수 있습니다.
응답 본문	엔드포인트가 반환한 본문입니다.

요청 탭

필드	설명
헤더	연결된 콘텐츠 태그에 포함된 헤더입니다(:headers, 자격 증명, :content_type 등의 옵션).
본문	전송된 요청 본문입니다(있는 경우, POST 요청).

디버거에 표시되는 요청 헤더

요청 탭에는 연결된 콘텐츠 태그의 헤더가 나열됩니다. 여기에는 커스텀 :headers, 저장된 자격 증명, 그리고 :content_type, :basic_auth 같은 태그 옵션으로 설정한 헤더가 포함됩니다. Braze는 엔드포인트로 보내는 요청에 표준 헤더(예: User-Agent, Host)도 추가합니다. 이렇게 Braze가 추가하는 헤더는 :headers에서 직접 설정한 경우에만 디버거에 표시됩니다.

Braze는 발신 연결된 콘텐츠 요청에 다음 헤더를 추가합니다. 대부분은 태그에서 아직 제공하지 않은 경우에만 설정됩니다. :headers, 자격 증명 또는 태그 옵션을 통해 제공한 헤더는 그대로 전송됩니다.

헤더	Braze가 설정하는 시점
User-Agent	아직 설정하지 않은 경우, Braze는 Braze Sender <version>을 전송합니다. 버전 문자열은 변경될 수 있습니다. User-Agent로 트래픽을 필터링하는 경우, Braze Sender로 시작하는 모든 값을 허용하세요. 일관된 값을 전송하려면 :headers에서 User-Agent를 설정하세요.
X-Braze-Sender-Version	항상 연결된 콘텐츠 발신자 버전으로 설정됩니다.
Accept-Encoding	아직 설정하지 않은 경우, Braze는 gzip을 전송합니다.
Authorization	URL에 사용자 이름과 비밀번호(user:pass@host)가 포함된 경우, Braze는 해당 자격 증명에서 파생된 Basic Authorization 헤더를 추가합니다. 명시적인 Authorization 헤더가 이를 재정의합니다. URL에 자격 증명을 넣는 대신 :basic_auth 또는 :headers를 사용하는 것이 좋습니다.
Host	Host 헤더를 설정하지 않은 경우, 요청 URL의 호스트 이름입니다(예: https://www.example.com/abc/123의 경우 www.example.com).
Content-Length	본문이 있는 경우, 요청 본문의 크기(바이트 단위)입니다.
BrazeToBraze	Braze REST 엔드포인트에 대한 요청에만 true로 설정됩니다. 다른 대상에는 생략됩니다.

자격 증명 마스킹

연결된 콘텐츠 태그에 :basic_auth, 일반적인 시크릿 헤더, 키 또는 기타 인증 자격 증명 옵션을 사용하는 경우, 디버거는 요청 탭에서 해당 값을 가리고 일련의 별표(*)로 대체합니다. 이렇게 하면 미리보기 및 테스트에서 값을 노출하지 않고도 요청에 자격 증명이 포함되었는지 확인할 수 있습니다.

자격 증명이 마스킹되더라도 인증 실패는 계속 확인할 수 있습니다. 엔드포인트가 401 또는 403을 반환하면 해당 상태 코드가 응답 탭에 정상적으로 표시됩니다. 따라서 자격 증명 자체는 숨겨져 있어도 요청이 인증 문제로 거부되었다는 사실을 알 수 있습니다.

응답 코드 문제 해결

엔드포인트 오류와 Braze 자체 제한의 차이

응답 탭에 표시되는 2XX 이외의 상태 코드가 모두 엔드포인트에서 발생하는 것은 아닙니다. Braze는 연결된 콘텐츠 호출에 자체 제한을 적용하며, 이 제한으로 인해 엔드포인트 오류와 비슷해 보이는 응답이 나타날 수 있습니다.

408, 429, 502, 503, 504, 599와 같은 응답 코드가 표시된다면, 문제는 대개 호출의 Braze 쪽에 있습니다. 주로 호스트 상태, 시간 초과 또는 페이로드 크기와 관련된 문제입니다. 엔드포인트가 계속해서 큰 응답을 반환한다면, 메시지에 필요한 필드만 남도록 응답 페이로드를 줄이는 것을 고려해 보세요.

엔드포인트가 예상치 못한 상태 코드를 반환함

요청 탭에서 URL, 태그의 헤더, 본문을 확인하세요. 예상치 못한 4XX 응답의 흔한 원인은 URL, 헤더 또는 본문 안의 Liquid 태그가 예상과 다르게 처리된 경우입니다. {{ }} 참조가 미리 보기에 사용 중인 사용자 또는 컨텍스트에 실제로 존재하는 필드를 가리키는지 확인하세요.

응답이 오래된 것처럼 보임

응답 탭에서 캐시에서 제공됨 항목을 확인하세요. 예로 표시되면 디버거가 새 호출이 아니라 이전에 캐시된 응답을 보여주고 있는 것입니다. 현재 엔드포인트 동작을 확인하려면 태그에 일시적으로 :no_cache를 추가하거나, 캐시가 만료될 때까지(:cache_max_age 기준) 기다리세요.

관련 문서

• 연결된 콘텐츠 참조
• 연결된 콘텐츠 API 호출하기
• 발신 요청 헤더
• 웹훅 및 연결된 콘텐츠 요청 문제 해결