연결된 콘텐츠 디버거

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

디버거 소개

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

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

지원 영역

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

• 배너
• Canvas 컨텍스트 단계
• Content Cards
• 이메일
  • 템플릿 포함
  • 푸터 및 구독 페이지 제외
• In-App Messages
• 푸시 알림
• SMS/MMS/RCS
• 웹훅
  • 템플릿 포함
• WhatsApp

디버거 사용하기

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

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

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

4. 각 URL과 성과 옆의 보기를 선택하여 요청 및 응답 헤더, 페이로드, 메서드, 소요 시간, 캐싱 정보를 확인합니다.

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

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

이러한 반복은 Braze가 메시지를 렌더링하고 발송하는 방식과 일치하며, 디버거는 이를 축소하지 않습니다. 호출 볼륨이 발송 수를 초과할 수 있는 이유에 대해 자세히 알아보려면 연결된 콘텐츠 호출 볼륨 이해하기를 참조하세요.

디버그 출력 이해하기

각 연결된 콘텐츠 호출은 고유한 Response 탭과 Request 탭으로 표시됩니다. Response 탭은 호출 성공 여부를 확인하는 첫 번째 지표이므로 기본적으로 표시됩니다.

URL 세부 정보

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

Response 탭

필드	설명
Duration	요청이 완료되기까지 걸린 시간(초)입니다. Duration은 실시간(캐시되지 않은) 호출에 대해서만 표시됩니다.
Served from cache	이 응답이 엔드포인트에 대한 실시간 호출이 아닌 Braze의 연결된 콘텐츠 캐시에서 제공되었는지 여부를 나타냅니다(Yes 또는 No). 캐시된 결과는 이전 응답을 반영하며, 반드시 엔드포인트의 현재 상태를 반영하지는 않습니다.
Response body	엔드포인트가 반환한 본문입니다.

Request 탭

필드	설명
Headers	연결된 콘텐츠 태그에서 가져온 헤더(:headers, 자격 증명, :content_type 등의 옵션)입니다.
Body	전송된 요청 본문(해당하는 경우, POST 요청)입니다.

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

Request 탭에는 연결된 콘텐츠 태그의 헤더가 나열됩니다: 커스텀 :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로 설정됩니다. 다른 대상에는 생략됩니다.

자격 증명 수정

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

자격 증명이 수정된 경우에도 인증 실패는 여전히 확인할 수 있습니다. 엔드포인트가 401 또는 403을 반환하면 해당 상태 코드가 Response 탭에 정상적으로 표시되므로, 자격 증명 자체는 숨겨져 있더라도 인증 문제로 요청이 거부되었음을 알 수 있습니다.

응답 코드 문제 해결

엔드포인트 오류와 Braze 제한 비교

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

408, 429, 502, 503, 504, 599와 같은 응답 코드가 표시되면, 일반적으로 호스트 상태, 시간 초과 또는 페이로드 크기와 관련된 Braze 측 문제입니다. 엔드포인트가 지속적으로 큰 응답을 반환하는 경우, 메시지에 필요한 필드만 포함하도록 응답 페이로드를 줄이는 것을 고려하세요.

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

Request 탭에서 URL, 태그의 헤더 및 본문을 확인하세요. 예상치 못한 4XX 응답의 일반적인 원인은 URL, 헤더 또는 본문 내의 Liquid 태그가 예상대로 확인되지 않는 경우입니다. {{ }} 참조가 미리보기에 사용 중인 사용자 또는 컨텍스트에 존재하는 필드를 가리키는지 확인하세요.

응답이 오래된 것처럼 보이는 경우

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

관련 문서

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