> 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/generating-ads/banner-x-responsive/bannerx-video-captions.md).

# Banner X 비디오 캡션

## 개요

이 Epsilon Retail Media 플랫폼은 다음을 위한 폐쇄 자막 및 전사 파일을 지원합니다: Banner X 비디오 캠페인. 광고주는 자막 파일(`.vtt`, `.srt`) 및 전사 파일(`.txt`)을 비디오 자산과 함께 업로드합니다. 연동 시 광고 응답에서 이러한 파일 URL을 소비하여 비디오 플레이어에 자막을 렌더링합니다.

이 연동은 공개용 비디오 콘텐츠에 사용자 제어 폐쇄 자막을 의무화하는 유럽 접근성법(EAA)과 같은 접근성 요구 사항을 충족하는 데 도움이 됩니다.

* 자막 파일은 비디오 플레이어용 시간 동기화 자막 트랙입니다.
* 전사 파일은 SEO 및 스크린 리더용 비디오 오디오 콘텐츠의 일반 텍스트 표현입니다.

이 가이드에서 다루는 내용:

* VAST 및 JSON 광고 응답에서 자막 및 전사 파일이 표시되는 방식
* VAST 4.3 `<ClosedCaptionFile>` 요소 구조
* JSON `videoTranscriptFiles[]` 배열 구조
* 제공된 CDN URL을 사용하여 자막을 렌더링하는 방법
* 테스트 및 검증

### 전달 모델

자막 파일 URL(`.vtt` / `.srt`)은 JSON이 아닌 VAST를 통해서만 전달됩니다.\
전사 파일 URL(`.txt`)은 VAST가 아닌 JSON을 통해서만 전달됩니다.\
자막은 비디오 플레이어에서 소비되며, 전사는 페이지 수준에서 소비됩니다.

## 연동 흐름

자막 및 전사 파일은 비디오 자산과 동일한 전달 경로를 따릅니다. 기존 외에 추가 API 호출이 필요하지 않습니다. Banner X 광고 요청.

1. 광고주는 캠페인 마법사를 통해 비디오, 자막 및 전사 파일을 업로드합니다.
2. 파일은 검증되고 저장되어 CDN을 통해 제공됩니다.
3. 기존 Banner X 광고 요청은 VAST의 자막 URL과 JSON의 전사 URL을 반환합니다.
4. 비디오 플레이어가 자막 파일 URL을 읽고 자막을 렌더링합니다.
5. 페이지는 선택적으로 접근성 또는 SEO를 위해 전사 텍스트를 표시합니다.

## 지원되는 파일 유형

| 자산     | 형식                               | 최대 크기                              |
| ------ | -------------------------------- | ---------------------------------- |
| 폐쇄 자막  | `.vtt` (WebVTT), `.srt` (SubRip) | 리테일러 콘텐츠 표준에 따라 설정 가능(일반적으로 1–4MB) |
| 트랜스크립트 | `.txt` (일반 텍스트)                  | 리테일러 콘텐츠 표준에 따라 설정 가능(일반적으로 1–4MB) |

파일은 있는 그대로 제공되며 플랫폼에서 형식을 변환하지 않습니다. 자막 렌더링은 사용하는 비디오 플레이어에서 담당합니다.

## 전제 조건

자막 및 트랜스크립트를 연동하기 전에 다음 사항을 확인하세요.

* 기존 Banner X 비디오 연동 — 이미 다 음을 소비하고 있습니다 `<MediaFiles>` adm 필드의 VAST 태그로부터. 참조 [비디오 광고](/retail-media-interface/integration/ko/generating-ads/banner-x-responsive/video-ads-banner-x.md) 자막 및 트랜스크립트 파일 전달이 포함된 전체 광고 응답 예시입니다.
* 자막을 지원하는 비디오 플레이어 — WebVTT 또는 SRT 자막 트랙(예: HTML5 `<track>` 요소 또는 이에 상응하는 네이티브 플레이어 API).
* 네임스페이스에 기능이 활성화됨 — 네임스페이스에 대한 자막 및 대본 업로드를 활성화하려면 계정 팀에 문의하세요.
* CORS가 구성됨 — 다음 위치로부터의 크로스 오리진 가져오기를 허용: `.vtt` 파일(다음에서 제공: Epsilon HTML5 사용 시 CDN 도메인) `<track>` 요소.

## 인증 및 보안

추가 인증이 필요하지 않습니다. 자막 및 대본 파일은 비디오 자산과 동일한 CDN을 통해 제공됩니다. 광고 응답에 반환된 파일 URL은 비디오 파일 URL과 동일한 보안 모델을 사용하여 공개적으로 액세스할 수 있습니다.

비디오 플레이어가 HTML5를 사용하는 경우 `<track>` 로드할 요소 `.vtt` 파일이 있는 경우 페이지의 콘텐츠 보안 정책이 다음 위치로부터의 가져오기를 허용하는지 확인하세요: Epsilon CDN 도메인. CDN은 크로스 오리진에 적합한 CORS 헤더를 설정합니다. `<track>` 로드 중입니다.

## 1단계: VAST 응답에서 자막 파일 파싱

**목적:** 비디오 플레이어에서 렌더링하기 위해 adm 필드의 VAST XML에서 시간 동기화된 자막 파일 URL을 검색합니다.

### 수행해야 할 작업

* VAST 파서에서 다음을 찾으세요: `<ClosedCaptionFiles>` 각 내의 요소 `<Linear>` 크리에이티브 (내부 `<MediaFiles>`).
* 각 `<ClosedCaptionFile>` 자식 요소에는 CDN URL이 텍스트 콘텐츠로 포함됩니다.
* 해당 `type` 속성은 MIME 유형 (`text/vtt` or `application/x-subrip` 은 SRT용)을 나타냅니다.
* 해당 `language` 속성은 자막 언어 (예: `en`).

### VAST 응답 예시

```xml
<Linear>
  <Duration></Duration>
  <MediaFiles>
    <ClosedCaptionFiles>
      <ClosedCaptionFile type="text/vtt" language="en"><![CDATA[https://dev12.flavedo.io./citrus/0f04cbc2-c933-4384-8d37-772e939d8d02]]></ClosedCaptionFile>
    </ClosedCaptionFiles>
    <Mezzanine><![CDATA[https://dev12.flavedo.io./citrus/37bb15a2-fd4d-4eb1-9dd7-7630b5df29d1]]></Mezzanine>
    <MediaFile delivery="progressive" type="video/mp4" width="1280" height="720" bitrate="8700" codec="h264"><![CDATA[https://dev12.flavedo.io./citrus/37bb15a2-fd4d-4eb1-9dd7-7630b5df29d1]]></MediaFile>
  </MediaFiles>
  <VideoClicks>
    <ClickTracking><![CDATA[https://integration.dev12.citrusad.com/v1/resource/second-c/...]]></ClickTracking>
    <ClickThrough></ClickThrough>
  </VideoClicks>
</Linear>
```

### 검증

* VAST 파서가 다음을 추출하는지 확인하세요. `<ClosedCaptionFile>` URL이 존재하는 경우.
* 파서가 다음이 없는 경우를 정상적으로 처리하는지 확인하세요. `<ClosedCaptionFiles>` (모든 캠페인에 자막이 포함되는 것은 아닙니다).

### 일반적인 오류

| 오류                             | 원인                                                                                      |
| ------------------------------ | --------------------------------------------------------------------------------------- |
| `<ClosedCaptionFiles>` 찾을 수 없음 | 캠페인에 승인된 자막 파일이 없거나 사용자의 환경에서 자막 전송이 아직 활성화되지 않았을 수 있습니다. 자막이 없는 캠페인의 경우 이는 정상적인 동작입니다. |

## 3단계: JSON 응답에서 트랜스크립트 파일 파싱

**목적:** SEO 또는 스크린 리더 접근성을 위해 JSON 광고 응답에서 일반 텍스트 트랜스크립트 파일 URL을 가져옵니다.

### 수행해야 할 작업

* 다음에서 Banner X 응답을 생성하고 각 광고 개체에서 다음을 찾습니다. `videoTranscriptFiles` 배열.
* 각 항목에는 다음이 포함됩니다. `videoFileId` 트랜스크립트를 해당 비디오와 일치시킬 수 있습니다.
* 트랜스크립트는 일반 텍스트 (`.txt`)입니다. SEO 메타데이터, 스크린 리더 또는 대체 텍스트 표시용으로 사용하세요.

### JSON 응답 예시

```json
"videoTranscriptFiles": [
  {
    "videoFileId": "a6f4c4a6-6982-4a8c-9a81-ecdfd4b3fa36",
    "format": "txt",
    "url": "https://dev12.flavedo.io./citrus/03d98ae2-67d5-49d3-9e9b-c8f278520657",
    "language": "en"
  }
]
```

### 검증

* JSON 파서가 다음을 읽는지 확인하세요. `videoTranscriptFiles` 배열이 존재하는 경우.
* 배열이 비어 있거나 없는 경우 정상적으로 처리되는지 확인하세요.

{% hint style="info" %}
자막 파일 URL ( `.vtt`/`.srt`용)은 JSON이 아닌 VAST를 통해서만 전송됩니다. 트랜스크립트 파일 (`.txt`)은 VAST가 아닌 JSON을 통해서만 전송됩니다. 이러한 분리는 서로 다른 소비 패턴을 반영합니다. 자막은 비디오 플레이어(VAST)용이고 트랜스크립트는 페이지 수준 접근성(JSON)용입니다.\*\*
{% endhint %}

## 3단계: 비디오 플레이어에 자막 렌더링

**목적:** 비디오 재생 중에 쇼핑객에게 자막을 표시합니다.

### 수행해야 할 작업

* VAST에서 자막 URL을 파싱한 후 다음을 추가합니다. `<track>` HTML5 비디오 플레이어(또는 네이티브 플레이어 SDK의 동급 요소)에 사용할 요소입니다.
* 설정 `kind="captions"`. 기본적으로 자막을 활성화하려면 다음을 사용하세요. `default` 속성을 사용합니다.
* .srt 파일의 경우 일부 플레이어는 런타임 시 WebVTT로 변환해야 합니다 (다음을 앞에 추가 `WEBVTT\n\n` 하고 타임스탬프의 쉼표를 마침표로 교체).

### HTML5 구현 예시

```html
<video controls crossorigin="anonymous">
  <source src="https://cdn.citrusad.com/video/abc123.mp4" type="video/mp4">
  <track
    kind="captions"
    src="https://cdn.citrusad.com/captions/def456.vtt"
    srclang="en"
    label="English"
    default
  >
</video>
```

### 검증

* 비디오를 재생하고 자막이 오버레이로 나타나는지 확인합니다.
* 쇼핑객이 플레이어 컨트롤을 통해 자막을 켜고 끌 수 있는지 확인합니다.
* 자막이 비디오 오디오와 시간 동기화되는지 확인합니다.

### 일반적인 오류

| 오류                        | 해결 방법                                                                        |
| ------------------------- | ---------------------------------------------------------------------------- |
| 자막이 로드되지 않음 (콘솔의 CORS 오류) | 콘텐츠 보안 정책 및 CORS 구성이 다음 수신을 허용하는지 확인하세요. `.vtt` 파일(다음에서 제공: Epsilon CDN 도메인. |
| 자막이 깨지거나 빈 상태로 표시됨        | 파일 URL이 유효한 WebVTT 콘텐츠를 반환하는지 확인하세요. URL을 직접 가져와 파일을 검사합니다.                  |

## 4단계: (선택 사항) 트랜스크립트 텍스트 표시

**목적:** 스크린 리더 및 SEO를 위해 비디오 옆이나 아래에 접근 가능한 텍스트 콘텐츠를 제공합니다.

### 수행해야 할 작업

* 다음에서 트랜스크립트 URL을 가져옵니다. `videoTranscriptFiles` JSON 응답의 항목입니다.
* 접근성, SEO, 스크린 리더 또는 기타 소매업체별 사용 사례에 트랜스크립트 텍스트를 사용하세요.

### 예시

```html
<details>
  <summary>Video transcript</summary>
  <p id="transcript-content"></p>
</details>
<script>
  fetch('https://cdn.citrusad.com/transcripts/ghi789.txt')
    .then(r => r.text())
    .then(text => {
      document.getElementById('transcript-content').textContent = text;
    });
</script>
```

## 데이터 모델 및 필드 정의

### VAST: `ClosedCaptionFile` 요소

| 속성 / 필드    | 유형        | 필수 여부 | 설명             | 허용되는 값                           |
| ---------- | --------- | ----- | -------------- | -------------------------------- |
| `type`     | 문자열       | 예     | 자막 파일의 MIME 유형 | `text/vtt, application/x-subrip` |
| `language` | 문자열       | No    | 자막 트랙의 언어      | e.g. `en`                        |
| 요소 텍스트     | 문자열 (URL) | 예     | 자막 파일의 CDN URL | HTTPS URL                        |

### JSON: `videoTranscriptFiles`

| 필드            | 유형        | 필수 여부 | 설명                    | 허용되는 값    |
| ------------- | --------- | ----- | --------------------- | --------- |
| `videoFileId` | 문자열       | 예     | 이 스크립트가 속한 비디오 파일의 ID | UUID      |
| `format`      | 문자열       | 예     | 스크립트의 파일 형식           | `txt`     |
| `url`         | 문자열 (URL) | 예     | 스크립트 파일의 CDN URL      | HTTPS URL |
| `language`    | 문자열       | 예     | 스크립트의 언어              | e.g. `en` |

## 하위 호환성

이러한 추가 사항은 완전한 하위 호환성을 제공합니다.

* 캠페인에 첨부된 자막 파일이 없는 경우, `<ClosedCaptionFiles>` 요소는 VAST에서 완전히 생략됩니다.
* 첨부된 스크립트 파일이 없는 경우, `videoTranscriptFiles` JSON에서 이 부분이 누락되거나 빈 배열로 표시됩니다.
* 이러한 새 요소를 구문 분석하지 않는 기존 연동은 변경 없이 계속 작동합니다.

## 테스트, 샌드박스 및 라이브 전환

### 샌드박스 / 테스트 환경

* 자막 및 스크립트 업로드가 활성화된 테스트 네임스페이스에 대한 액세스를 요청하세요(계정 담당 팀에 문의).
* 샘플로 테스트 캠페인 업로드 `.vtt` 캠페인 마법사를 통한 캡션 파일입니다.
* 검토 주기를 통해 캠페인을 승인합니다.
* 다음으로 전화하십시오: Banner X generate 엔드포인트를 호출하고 VAST 및 JSON 응답을 검사합니다.

### 샘플 테스트 케이스

| 테스트            | 단계                           | 예상 결과                                                |
| -------------- | ---------------------------- | ---------------------------------------------------- |
| VAST 캡션 있음     | 승인된 캠페인에 대한 광고 요청 `.vtt` 캡션  | VAST에 다음이 포함됨: `<ClosedCaptionFiles>` 유효한 CDN URL 사용 |
| VAST 캡션 없음     | 캡션이 없는 캠페인에 대한 광고 요청         | No `<ClosedCaptionFiles>` VAST의 요소                   |
| JSON 자막 있음     | 승인된 캠페인에 대한 광고 요청 `.txt` 자막  | JSON에 다음이 포함됨: `videoTranscriptFiles` 항목이 있는 배열      |
| 캡션 파일 접근 가능    | VAST 응답에서 직접 CDN URL을 가져옵니다. | 유효한 값을 반환합니다. `WebVTT` WEBVTT 헤더가 있는 콘텐츠             |
| 플레이어가 캡션을 렌더링함 | 플레이어에 비디오 + 캡션 트랙 로드         | 비디오 오디오와 시간에 맞춰 동기화되어 표시되는 캡션                        |
| 트랙 요소에 대한 CORS | 로드 `.vtt` 통해 `<track>` 교차 출처 | 브라우저 콘솔에 CORS 오류가 없으며 자막이 렌더링됨                       |

### 고라이브 점검목록

* [ ] VAST 파서가 추출함 `<ClosedCaptionFile>` 존재하는 경우 URL
* [ ] JSON 파서가 읽음 `videoTranscriptFiles[]` 존재하는 경우
* [ ] 자막이나 트랜스크립트가 없을 때 적절한 대체 작동
* [ ] 비디오 플레이어가 CDN URL에서 자막을 렌더링함
* [ ] 쇼핑객이 자막을 켜고 끌 수 있음
* [ ] 교차 출처에 대해 CORS 검증됨 `.vtt` 패치
* [ ] 트랜스크립트 텍스트 접근 가능 (4단계를 구현하는 경우)
* [ ] 둘 다로 테스트됨 `.vtt` 및 `.srt` 자막 형식

## 문제 해결 및 자주 묻는 질문

### `<ClosedCaptionFiles>` 요소가 VAST 응답에서 누락됨

**원인 가능성:** 캠페인에 승인된 자막 파일이 없거나 사용자의 환경에서 자막 전송이 활성화되지 않았습니다.

**해결 방법:**

* 캠페인에 승인된 자막 파일(업로드 및 검토 통과)이 있는지 확인합니다.
* 어카운트 팀에 연락하여 네임스페이스에 대해 해당 기능이 활성화되어 있는지 확인합니다.

### 로드 시 CORS 오류 발생 `.vtt` 통해 `<track>` 요소

**원인 가능성:** 콘텐츠 보안 정책 또는 브라우저 CORS 적용으로 인해 교차 출처 패치가 차단됨 `.vtt` 파일.

**해결 방법:**

* 추가 Epsilon 콘텐츠 보안 정책의 CDN 도메인 `connect-src` 및 `media-src` 지시문.
* 설정 `crossorigin="anonymous"` 부모의 `<video>` 요소(필요한 경우).

### 자막이 렌더링되지만 비디오와 동기화되지 않음

**원인 가능성:** 자막 파일이 잘못된 타임스탬프로 작성되었거나, 변환 없이 VTT로 로드되는 SRT 파일입니다.

**해결 방법:**

* 자막 파일 URL을 가져와 비디오 재생에 맞춰 타임스탬프를 검사합니다.
* 파일이 .srt이고 플레이어가 .vtt만 지원하는 경우 런타임에 변환합니다(맨 앞에 추가 `WEBVTT\n\n`, 교체 `,` 과/와 `.` 타임스탬프에서).

### 트랜스크립트 URL이 404를 반환함

**원인 가능성:** 캠페인이 업데이트되어 트랜스크립트 파일이 삭제되었거나 CDN 전파 지연이 발생했습니다.

**해결 방법:**

* 광고 응답을 다시 가져와 현재 파일 URL을 얻습니다.
* 문제가 지속되면 지원팀에 문의하세요.

지원팀에 문의할 때 다음 정보를 포함하세요:

* generate 호출의 요청 ID 또는 상관 관계 ID
* 광고 요청의 타임스탬프(UTC)
* 해당 `<ClosedCaptionFile>` or `videoTranscriptFiles` 실패하는 URL
* 브라우저 콘솔 오류(CORS 문제의 경우)
* 네임스페이스 및 캠페인 ID

## 관련 문서

* [비디오 광고](/retail-media-interface/integration/ko/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [다양한 게재위치에 대한 배너 X 광고 생성](/retail-media-interface/integration/ko/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [배너 X 레퍼런스](/retail-media-interface/integration/ko/references/banner-x-reference-1.md)
* [배너 X 미리보기](/retail-media-interface/integration/ko/generating-ads/banner-x-responsive/integrating-your-banner-x-previewer.md)

<br>


---

# 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/generating-ads/banner-x-responsive/bannerx-video-captions.md?ask=<question>&goal=<endgoal>
```

`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.