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

# Titulky k videu Banner X

## Prehľad

Platforma Epsilon Retail Media platforma podporuje súbory so skrytými titulkami a prepismi pre Banner X videokampane. Inzerenti nahrávajú súbory titulkov (`.vtt`, `.srt`) a súbory prepisov (`.txt`) popri svojich video podkladoch. Vaša integrácia spracúva tieto URL adresy súborov z odpovede na reklamu a zobrazuje titulky vo vašom prehrávači videa.

Táto integrácia vám pomáha spĺňať požiadavky na prístupnosť, ako je Európsky akt o prístupnosti (EAA), ktorý vyžaduje používateľom ovládané skryté titulky pri video obsahu určenom pre verejnosť.

* Súbory titulkov sú časovo synchronizované stopy titulkov pre váš prehrávač videa.
* Súbory prepisov sú textové reprezentácie audio obsahu videa pre účely SEO a čítačky obrazovky.

Tento sprievodca pokrýva:

* Ako sa súbory titulkov a prepisov zobrazujú v odpovediach na reklamu VAST a JSON
* VAST 4.3 `<ClosedCaptionFile>` štruktúra prvku
* JSON `videoTranscriptFiles[]` štruktúra poľa
* Ako zobrazovať titulky pomocou poskytnutých URL adries z CDN
* Testovanie a overenie

### Model doručovania

URL adresy súborov titulkov (`.vtt` / `.srt`) sa doručujú iba cez VAST, nie cez JSON.\
URL adresy súborov prepisov (`.txt`) sa doručujú iba cez JSON, nie cez VAST.\
Titulky spracúva váš prehrávač videa; prepisy sa spracúvajú na úrovni stránky.

## Tok integrácie

Súbory titulkov a prepisov nasledujú rovnakú trasu doručenia ako video podklady. Okrem vašej existujúcej Banner X žiadosti o reklamu nie sú potrebné žiadne ďalšie volania API.

1. Inzerent nahrá video, súbory titulkov a prepisov prostredníctvom sprievodcu kampanou.
2. Súbory sa overia, uložia a poskytujú prostredníctvom CDN.
3. Vaša existujúca Banner X žiadosť o reklamu vracia URL adresy titulkov vo VAST a URL adresy prepisov v JSON.
4. Váš prehrávač videa prečíta URL adresu súboru titulkov a zobrazí titulky.
5. Vaša stránka voliteľne zobrazí text prepisu pre prístupnosť alebo SEO.

## Podporované typy súborov

| Podklad        | Formáty                          | Maximálna veľkosť                                                  |
| -------------- | -------------------------------- | ------------------------------------------------------------------ |
| Skryté titulky | `.vtt` (WebVTT), `.srt` (SubRip) | Konfigurovateľné podľa štandardu obsahu predajcu (zvyčajne 1–4 MB) |
| Prepis         | `.txt` (čistý text)              | Konfigurovateľné podľa štandardu obsahu predajcu (zvyčajne 1–4 MB) |

Súbory sa poskytujú tak, ako sú; platforma nekonvertuje formáty. Za zobrazenie titulkov zodpovedá váš prehrávač videa.

## Predpoklady

Pred integráciou titulkov a prepisov potvrďte nasledujúce:

* Existujúca Banner X integrácia videa — už spracúvate `<MediaFiles>` z značky VAST v poli adm. Pozrite si [Video reklamy](/retail-media-interface/integration/sk/generating-ads/banner-x-responsive/video-ads-banner-x.md) , kde nájdete úplný príklad odpovede na reklamu, ktorý zahŕňa doručenie súborov titulkov a prepisov.
* Prehrávač videa s podporou titulkov — stopy titulkov WebVTT alebo SRT (napr. HTML5 `<track>` prvok alebo ekvivalentné natívne API prehrávača).
* Funkcia povolená pre váš jenný priestor — kontaktujte svoj tím pre správu účtu a nechajte si povoliť nahrávanie titulkov a prepisov pre váš menný priestor.
* Nakonfigurované CORS — povolenie načítavania cez rôzne pôvody (cross-origin fetch) pre `.vtt` súbory z domény Epsilon CDN pri použití HTML5 `<track>` prvkov.

## Autentifikácia a bezpečnosť

Nevyžaduje sa žiadna ďalšia autentifikácia. Súbory titulkov a prepisov sa poskytujú prostredníctvom rovnakej CDN ako video podklady. URL adresy súborov vrátené v odpovedi na reklamu sú verejne prístupné a používajú rovnaký bezpečnostný model ako URL adresy súborov videa.

Ak váš prehrávač videa používa HTML5 `<track>` prvky na načítanie `.vtt` súborov, uistite sa, že zásady bezpečnosti obsahu (Content Security Policy) vašej stránky povoľujú načítavanie z domény Epsilon CDN. CDN nastavuje príslušné hlavičky CORS pre načítavanie cez rôzne pôvody (cross-origin `<track>` loading).

## Krok 1: Parsujte súbory titulkov z odpovede VAST

**Účel:** Získanie URL adries časovo synchronizovaných súborov titulkov z VAST XML v poli adm na zobrazenie vo vašom prehrávači videa.

### Čo musíte urobiť

* Vo vašom parseri VAST vyhľadajte `<ClosedCaptionFiles>` prvok v rámci každého `<Linear>` reklamný materiál (vnútri `<MediaFiles>`).
* Každý `<ClosedCaptionFile>` dlaždicový prvok obsahuje URL adresu CDN ako svoj textový obsah.
* Atribút `type` atribút uvádza typ MIME (`text/vtt` or `application/x-subrip` pre SRT).
* Atribút `language` atribút uvádza jazyk titulkov (napr. `en`).

### Príklad odpovede 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>
```

### Validácia

* Overte, že váš parser VAST extrahuje `<ClosedCaptionFile>` URL, ak je prítomná.
* Overte, že váš parser bez problémov zvládne absenciu `<ClosedCaptionFiles>` (nie všetky kampane obsahujú titulky).

### Bežné chyby

| Chyba                            | Príčina                                                                                                                                                         |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<ClosedCaptionFiles>` nenájdené | Kampaň nemusí mať schválený súbor s titulkami alebo doručovanie titulkov ešte nie je pre vaše prostredie povolené. Toto sa očakáva pri kampaniach bez titulkov. |

## Krok 2: Analyzujte súbory prepisov z odpovede JSON

**Účel:** Získať URL adresy textových súborov s prepisom z ad odpovede JSON pre SEO alebo prístupnosť pre čítačky obrazovky.

### Čo musíte urobiť

* V Banner X vygenerovať odpoveď, vyhľadajte `videoTranscriptFiles` pole na každom objekte reklamy.
* Každá položka obsahuje `videoFileId` aby ste mohli priradiť prepisy k ich zodpovedajúcemu videu.
* Prepisy sú v čistom texte (`.txt`) — použite ich pre metaúdaje SEO, čítačky obrazovky alebo alternatívne zobrazenie textu.

### Príklad odpovede JSON

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

### Validácia

* Overte, že váš JSON parser číta `videoTranscriptFiles` pole, ak je prítomné.
* Overte bezproblémové spracovanie, keď je pole prázdne alebo chýba.

{% hint style="info" %}
URL adresy súborov s titulkami (pre `.vtt`/`.srt`) sa doručujú iba cez VAST, nie cez JSON. Súbory s prepisom (`.txt`) sa doručujú iba cez JSON, nie cez VAST. Toto rozdelenie odrkadľuje rôzne vzorce spotreby: titulky sú pre prehrávače videa (VAST), prepisy sú pre prístupnosť na úrovni stránky (JSON).\*\*
{% endhint %}

## Krok 3: Rendorovanie titulkov vo vašom prehrávači videa

**Účel:** Zobraziť skryté titulky nakupujúcim počas prehrávania videa.

### Čo musíte urobiť

* Po analýze URL adresy titulkov z VAST pridajte `<track>` prvok do vášho HTML5 prehrávača videa (alebo ekvivalent vo vašom natívnom SDK prehrávači).
* Nastavte `kind="captions"`. Použite `default` atribút, ak chcete, aby boli titulky povolené ako predvolené.
* Pre súbory .srt niektoré prehrávače vyžadujú konverziu na WebVTT počas spustenia (predraďte `WEBVTT\n\n` a nahraďte čiarku bodkou v časových pečiatkach).

### Príklad HTML5 implementácie

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

### Validácia

* Pusťte video a overte, že sa titulky zobrazujú ako prekrytie.
* Overte, že nakupujúci môže zapnúť/vypnúť titulky pomocou ovládacích prvkov prehrávača.
* Overte, že titulky sú časovo synchronizované s zvukom videa.

### Bežné chyby

| Chyba                                        | Riešenie                                                                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Titulky sa nenačítajú (chyba CORS v konzole) | Uistite sa, že vaša konfigurácia Zásad bezpečnosti obsahu a CORS umožňuje načítanie `.vtt` súbory z domény Epsilon CDN doména. |
| Titulky sa zobrazujú skomolené alebo prázdne | Overte, či URL adresa súboru vracia platný obsah WebVTT. Načítajte URL adresu priamo a skontrolujte súbor.                     |

## Krok 4: (Voliteľné) Zobrazenie textu prepisu

**Účel:** Poskytnúť prístupný textový obsah vedľa alebo pod videom pre čítačky obrazovky a SEO.

### Čo musíte urobiť

* Načítajte URL adresu prepisu z `videoTranscriptFiles` položky v odpovedi JSON.
* Použite text prepisu pre prístupnosť, SEO, čítačky obrazovky alebo iné prípady použitia špecifické pre predajcu.

### Príklad

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

## Dátové modely a definície polí

### VAST: `ClosedCaptionFile` prvok

| Atribút / pole | Typ          | Povinné | Popis                                | Akceptované hodnoty              |
| -------------- | ------------ | ------- | ------------------------------------ | -------------------------------- |
| `type`         | string       | Áno     | MIME typ súboru s titulkami          | `text/vtt, application/x-subrip` |
| `language`     | string       | No      | Jazyk stopy titulkov                 | e.g. `en`                        |
| Text prvku     | string (URL) | Áno     | URL adresa súboru s titulkami na CDN | HTTPS URL                        |

### JSON: `videoTranscriptFiles`

| Pole          | Typ          | Povinné | Popis                                          | Akceptované hodnoty |
| ------------- | ------------ | ------- | ---------------------------------------------- | ------------------- |
| `videoFileId` | string       | Áno     | ID video súboru, ku ktorému tento prepis patrí | UUID                |
| `format`      | string       | Áno     | Formát súboru prepisu                          | `txt`               |
| `url`         | string (URL) | Áno     | URL adresa súboru s prepisom na CDN            | HTTPS URL           |
| `language`    | string       | Áno     | Jazyk prepisu                                  | e.g. `en`           |

## Spätná kompatibilita

Tieto prídavky sú plne spätne kompatibilné:

* Ak k kampani nie sú priložené žiadne súbory s titulkami, `<ClosedCaptionFiles>` prvok sa vo VAST úplne vynechá.
* Ak nie sú priložené žiadne súbory s prepisom, `videoTranscriptFiles` v JSON chýba alebo je prázdnym poľom.
* Existujúce integrácie, ktoré nespracovávajú tieto nové prvky, fungujú aj naďalej bez zmien.

## Testovanie, sandbox a spustenie do ostrej prevádzky

### Sandbox / testovacie prostredie

* Požiadajte o prístup k testovaciemu mennému priestoru s povoleným nahrávaním titulkov a prepisov (kontaktujte svoj klientsky tím).
* Nahrajte testovaciu kampaň so vzorovým `.vtt` súborom titulkov cez sprievodcu kampaňou.
* Schváľte kampaň cez schvaľovací cyklus.
* Zavolajte Banner X koncový bod generate a skontrolujte odpoveď VAST a JSON.

### Vzorové testovacie prípady

| Test                        | Kroky                                                           | Očakávaný výsledok                                             |
| --------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
| Titulky VAST sú prítomné    | Požiadajte o reklamu pre kampaň so schválenými `.vtt` titulkami | VAST obsahuje `<ClosedCaptionFiles>` s platnou CDN URL adresou |
| Titulky VAST chýbajú        | Požiadajte o reklamu pre kampaň bez titulkov                    | No `<ClosedCaptionFiles>` prvok vo VAST                        |
| JSON prepis je prítomný     | Požiadajte o reklamu pre kampaň so schválenými `.txt` prepis    | JSON obsahuje `videoTranscriptFiles` pole s položkou           |
| Súbor titulkov je prístupný | Načítajte CDN URL priamo z odpovede VAST                        | Vráti platný `WebVTT` obsah s hlavičkou WEBVTT                 |
| Prehrávač zobrazuje titulky | Načítajte video + stopu titulkov do prehrávača                  | Titulky sa zobrazujú časovo synchronizované so zvukom videa    |
| CORS pre prvok track        | Načítať `.vtt` cez `<track>` cross-origin                       | Žiadne chyby CORS v konzole prehliadača; titulky sa zobrazujú  |

### Kontrolný zoznam pred spustením

* [ ] VAST parser extrahuje `<ClosedCaptionFile>` URL adresy, ak sú prítomné
* [ ] JSON parser číta `videoTranscriptFiles[]` ak je prítomné
* [ ] Keď titulky alebo prepisy chýbajú, použije sa bezproblémové náhradné riešenie
* [ ] Video prehrávač zobrazuje titulky z URL adresy CDN
* [ ] Kupujúci môže zapnúť/vypnúť titulky
* [ ] CORS overené pre cross-origin `.vtt` načítanie (fetch)
* [ ] Text prepisu je prístupný (ak implementujete krok 4)
* [ ] Testované s oboma `.vtt` a `.srt` formátmi titulkov

## Riešenie problémov a často kladené otázky

### `<ClosedCaptionFiles>` prvok chýba v odpovedi VAST

**Pravdepodobná príčina:** Kampaň nemá schválený súbor s titulkami alebo doručovanie titulkov nie je vo vašom prostredí povolené.

**Riešenie:**

* Potvrďte, že kampaň má schválený súbor s titulkami (nahraný a prešiel kontrolou).
* Obráťte sa na svoj účtovný tím a overte, či je táto funkcia povolená pre váš namespace.

### Chyba CORS pri načítavaní `.vtt` cez `<track>` prvok

**Pravdepodobná príčina:** Zásady bezpečnosti obsahu (CSP) alebo presadzovanie CORS v prehliadači blokujú načítanie cross-origin súboru `.vtt` .

**Riešenie:**

* Pridajte Epsilon doménu CDN do svojich Zásad bezpečnosti obsahu `connect-src` a `media-src` direktív.
* Nastavte `crossorigin="anonymous"` na nadriadenom `<video>` prvku, ak sa vyžaduje.

### Titulky sa zobrazujú, ale nie sú synchronizované s videoma

**Pravdepodobná príčina:** Súbor s titulkami bol vytvorený s nesprávnymi časovými značkami alebo súbor SRT sa načítava ako VTT bez konverzie.

**Riešenie:**

* Načítajte URL adresu súboru s titulkami a skontrolujte časové značky oproti prehrávaniu videa.
* Ak je súbor typu .srt a váš prehrávač podporuje iba .vtt, skonvertujte ho počas spúšťania (predraďte `WEBVTT\n\n`, nahraďte `,` za `.` v časových značkách).

### URL adresa prepisu vracia 404

**Pravdepodobná príčina:** Kampaň bola aktualizovaná a súbor s prepisom bol odstránený, alebo ide o kaštanové opozdenie propagácie CDN.

**Riešenie:**

* Znova načítajte odpoveď na reklamu, aby ste získali aktuálnu URL adresu súboru.
* Ak problém pretrváva, kontaktujte podporu.

Pri kontaktovaní podpory uveďte:

* ID požiadavky (Request ID) alebo ID korelácie z volania generate
* Časovú značku (UTC) požiadavky na reklamu
* Atribút `<ClosedCaptionFile>` or `videoTranscriptFiles` URL adresu, ktorá zlyháva
* Chybu v konzole prehliadača (pri problémoch s CORS)
* Namespace a ID kampane

## Súvisiace články

* [Video reklamy](/retail-media-interface/integration/sk/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [Vygenerujte Banner X reklamy pre rôzne umiestnenia](/retail-media-interface/integration/sk/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [Referencia pre Banner X](/retail-media-interface/integration/sk/references/banner-x-reference-1.md)
* [Nástroj na náhľad Banner X](/retail-media-interface/integration/sk/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/sk/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.