> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/ko/brand-pages/brand-page-retailer-integration-guide/validation-troubleshooting.md).
# 유효성 검사 및 문제 해결
## 테스트 및 유효성 검사
### 출시 전 유효성 검사 체크리스트
**기술 연동**
* [ ] API :`POST /ads/v3/brand-pages` 이 200을 반환함 `contentData`.
* [ ] 렌더링 : 콘텐츠 모듈이 사이트에 올바른 순서로 올바르게 렌더링됨.
* [ ] 테마: `theme` 필드가 올바르게 적용됨; `null` 값은 리테일러 스타일 가이드 기본값으로 대체됨.
* [ ] 선택적 필드: 렌더러 및 트래킹 로직은 누락되거나, null이거나, 비어 있는 선택적 모듈 필드와 누락된 트래킹 노드를 오류 없이 처리해야 함(단일 데모 브랜드 페이지뿐만 아니라 여러 라이브 템플릿을 사용하여 유효성을 검사하세요).
* [ ] 스타일링 : 브랜드 페이지가 사이트의 디자인 시스템과 일치함.
* [ ] 모바일 : 브랜드 페이지가 모바일 기기에서 올바르게 표시됨.
* [ ] 캐시 무효화(Cache-busting) : `{TS}` 값이 모든 요청마다 변경됨.
**트래킹 유효성 검사**
* [ ] 노출 픽셀 (C2S) : 다음의 모든 항목 `trackingTemplates.client.impressionPixelUrls` 이 실행되어 200을 반환함 `image/gif`
* [ ] 노출 알림 (S2S) : 생성된 서버 노출 URL; Epsilon 트래킹 호스트로 직접 **GET** 또는 **POST** 요청 시 204 No Content 반환.
* [ ] 클릭 트래킹 (C2S) : 생성된 `client.clickRedirect` URL이 올바른 목적지로 302를 반환하거나, 생성된 `client.clickEvent` 이 204 No Content를 반환함 (플로우에서 사용하는 옵션 하나만 해당 - 둘 다는 안 됨)
* [ ] 클릭 알림 (S2S) : 생성된 서버 URL로 직접 **GET** 또는 **POST** 요청 시 204 No Content 반환
* [ ] 장바구니 담기 (C2S) : 이벤트 비콘으로 실행된 생성된 `client.addToCartEvent` 이 204 No Content를 반환함
* [ ] 장바구니 담기 (S2S) : 트래킹 호스트로 직접 호출된 생성된 `server.addToCartEvent` 이 204 No Content를 반환함
**인프라 및 개인정보 보호**
* [ ] 리버스 프록시 : 도메인을 통해 전달되는 C2S 트래킹 요청; S2S는 프록시를 통해 전송되지 않음
* [ ] 헤더 : `RP-Host`, `X-Forwarded-For`, `X-Forwarded-Request-Path`, `Referer` 이 프록시된 요청에 존재함
* [ ] 개인정보 보호 : 어떠한 파라미터나 URL에도 PII가 존재하지 않음
* [ ] HTTPS : 모든 요청은 보안 연결을 사용함
* [ ] 상품 페이지 : 클릭 리디렉션 후 페이지가 올바르게 렌더링됨
### 권장 도구
* 브라우저 개발자 도구: 픽셀 로드 및 리디렉션을 검사하는 네트워크 탭.
* Fiddler 또는 Charles Proxy: 역방향 프록시 동작 및 헤더 전달을 검사합니다.
### 문제 해결
| 문제 | 확인 사항 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 픽셀을 로드하지 못함 | DNS/SSL을 확인하고, 프록시 경로 재작성을 확인하며, 다음으로의 접근 가능성을 확인하세요: Epsilon 추적 호스트. |
| 리디렉션이 전달되지 않음 | 다음 사항을 확인하세요: `{RURL}` 이(가) URL 인코딩되어 있는지 확인하고, 프록시가 쿼리 스트링을 보존하는지 확인하세요. |
| API가 콘텐츠를 반환하지 않음 | 확인 `catalogId` 및 `urlSlug` 활성 브랜드 페이지 캠페인과 일치합니다. |
| 광고 차단기에 의해 추적이 차단됨 | 역방향 프록시가 구성되어 있는지 확인하세요. 추적이 도메인을 통해 라우팅되어야 합니다. |
| 장바구니 담기가 추적되지 않음 | 장바구니 작업 후 작성된 클라이언트 또는 서버 장바구니 담기 URL을 실행했는지 확인하세요. |
| 일부 브랜드 페이지를 로드할 때 페이지 오류가 발생함 | doc/example 필드를 항상 필수인 것으로 처리하고 있을 가능성이 높습니다. 원시 모듈 JSON을 기록하고, 선택적 키 및 누락된 추적에 대한 가드를 추가하며, 템플릿이 해당 필드를 허용하거나 비활성화하는지 확인하세요. |
| 테마 색상이 올바르게 적용되지 않음 | 다음 사항을 확인하세요: `null` 테마 필드가 리터럴 null 값이나 빈 문자열로 렌더링되지 않고 스타일 가이드 기본값으로 대체되는지 확인합니다. |
## 용어집
**브랜드 페이지 연동에 필요한 필수 용어**
| 용어 | 정의 | 예시 |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| API 키 | 다음에 대한 인증 자격 증명: Epsilon 서비스 | `Basic abc123xyz...` |
| 브랜드 페이지 | 사이트의 브랜드 랜딩 페이지 환경 | yoursite.com/brands/nike |
| C2S 추적 | Client-to-Server: 브라우저 기반 추적. 노출은 1x1 픽셀을 사용하며, 클릭은 302 리디렉션 또는 이벤트 비콘을 사용하고, 장바구니 담기는 이벤트 비콘을 사용합니다. | `
, navigator.sendBeacon(clickEvent)` |
| S2S 추적 | Server-to-Server: 백엔드 추적(조합된 추적 URL에 대한 GET 또는 POST) | 귀하의 서버 → Epsilon 서버 |
| 콘텐츠 모듈 | 개별 콘텐츠 블록(히어로, 텍스트, 상품 등) | 히어로 배너, 상품 그리드 |
| 모듈 태그 | 템플릿에 설정된 모듈의 선택적 문자열 레이블(예: `["header"]`). 레이아웃 라우팅, 분석 또는 자체 구성 요소에 대한 매핑을 위해 리테일러가 사용합니다. 비어 있는 경우 응답에서 생략됩니다. | `"tags": ["header"]` |
| 테마 | 성공 시 API 응답에 항상 존재: 중첩된 `colors` (배경 + 7개 텍스트 역할) 및 `buttons` (`primary` / `secondary` 함께 `background` 및 `text`). 모든 테마 색상 필드는 필수 항목입니다(hex6). 참조: [테마 개체](/retail-media-interface/integration/ko/brand-pages/brand-page-retailer-integration-guide/brand-page-apis.md#theme-object). | "theme": { "colors": { ... }, "buttons": { ... } } |
| 노출 | 사용자가 브랜드 페이지를 조회할 때 | 페이지 로드 = 노출 1회 |
| 클릭 | 사용자가 브랜드 페이지 콘텐츠를 클릭할 때 | CTA 버튼 클릭 |
| 전환 | 사용자가 브랜드 페이지에서 상품을 장바구니에 담을 때 | 장바구니 담기 작업 |
| 리버스 프록시 | 광고 차단기를 우회하기 위해 도메인을 통해 추적을 라우팅합니다. | `yoursite.com/epsilon/` → Epsilon |
| URL 슬러그 | URL 경로의 브랜드 식별자 | `nike` in `/brands/nike` |
| 카탈로그 ID | 고유한 상품 카탈로그 식별자 | 제공자: Epsilon |
| 매크로 | 응답 자리 표시자(`{TS}`, `{RURL}`) in `tracking.params` 런타임에 교체하는 값; | `{TS} → 1737485823910` |
| IAB TCF | Interactive Advertising Bureau Transparency & Consent Framework | GDPR 준수 표준 |
| PII | 개인 식별 정보(절대 전송하지 마세요!) | 이메일, 전화번호, 실명 |
| 캐시 버스팅 | 캐시된 응답을 방지하기 위해 타임스탬프 추가 | `?ts=1737485823910` |
### 기술 약어
| 약어 | 전체 용어 | 의미 |
| ----- | ---------------------------------- | ----------------- |
| RMN | Retail Media 네트워크 | Epsilon의 광고 플랫폼 |
| CTA | Call-to-Action | 클릭 가능한 버튼/링크 |
| JSON | JavaScript Object Notation | API 요청/응답용 데이터 형식 |
| HTTPS | HTTP Secure | 암호화된 웹 프로토콜 |
| GDPR | General Data Protection Regulation | EU 개인정보 보호법 |
| TLS | Transport Layer Security | 암호화 프로토콜 |
| DNS | Domain Name System | 인터넷 주소 시스템 |
| SSL | Secure Sockets Layer | 암호화 프로토콜 |
| RFC | Request for Comments | 기술 표준 문서 |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.citrusad.com/retail-media-interface/integration/ko/brand-pages/brand-page-retailer-integration-guide/validation-troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.