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

# Banner X videófeliratok

## Áttekintés

A Epsilon Retail Media platform támogatja a zárt láncú felirat- és átiratfájlokat a Banner X videókampányokhoz. A hirdetők feliratfájlokat (`.vtt`, `.srt`) és átiratfájlokat (`.txt`) töltenek fel a videóeszközeik mellé. Az Ön integrációja beolvassa ezeket a fájl-URL-eket a hirdetésválaszból, és megjeleníti a feliratokat a videólejátszóban.

Ez az integráció segít megfelelni az olyan hozzáférhetőségi követelményeknek, mint az Európai Akadálymentesítési Act (EAA), amely felhasználó által vezérelhető zárt feliratokat ír elő a nyilvános videótartalmaknál.

* A feliratfájlok időszinkronizált feliratsávok a videólejátszóhoz.
* Az átiratfájlok a videó hangtartalmának egyszerű szöveges ábrázolásai SEO és képernyőolvasó használatához.

Ez az útmutató a következőket tartalmazza:

* Hogyan jelennek meg a felirat- és átiratfájlok a VAST és JSON hirdetésválaszokban
* VAST 4.3 `<ClosedCaptionFile>` elem szerkezete
* JSON `videoTranscriptFiles[]` tömb szerkezete
* Hogyan jeleníthetők meg a feliratok a megadott CDN URL-ek használatával
* Tesztelés és ellenőrzés

### Kézbesítési modell

A feliratfájlok URL-jei (`.vtt` / `.srt`) csak VAST-on keresztül érkeznek, JSON-on keresztül nem.\
Az átiratfájlok URL-jei (`.txt`) csak JSON-on keresztül érkeznek, VAST-on keresztül nem.\
A feliratokat a videólejátszó használja fel; az átiratokat az oldal szintjén használják fel.

## Integrációs folyamat

A felirat- és átiratfájlok ugyanazt a kézbesítési útvonalat követik, mint a videóeszközök. Nincs szükség további API-hívásokra a meglévő Banner X hirdetési kérésen kívül.

1. A hirdető videó-, felirat- és átiratfájlokat tölt fel a kampányvarázslón keresztül.
2. A fájlok ellenőrzése, tárolása és kiszolgálása CDN-en keresztül történik.
3. A meglévő Banner X hirdetési kérése felirat-URL-eket ad vissza a VAST-ban és átirat-URL-eket a JSON-ban.
4. A videólejátszó beolvassa a feliratfájl URL-jét, és megjeleníti a feliratokat.
5. Az Ön oldala opcióként megjeleníti az átiratszöveget a hozzáférhetőség vagy a SEO érdekében.

## Támogatott fájltípusok

| Eszköz               | Formátumok                       | Max. méret                                                                  |
| -------------------- | -------------------------------- | --------------------------------------------------------------------------- |
| Zárt láncú feliratok | `.vtt` (WebVTT), `.srt` (SubRip) | Kereskedőnkénti tartalomstandard alapján konfigurálható (jellemzően 1–4 MB) |
| Átirat               | `.txt` (egyszerű szöveg)         | Kereskedőnkénti tartalomstandard alapján konfigurálható (jellemzően 1–4 MB) |

A fájlok kiszolgálása eredeti formájukban történik; a platform nem konvertálja a formátumokat. A feliratok megjelenítéséért a videólejátszó felelős.

## Előfeltételek

A feliratok és átiratok integrálása előtt erősítse meg a következőket:

* Meglévő Banner X videóintegráció — Ön már beolvassa a következőt: `<MediaFiles>` az adm mezőben lévő VAST-címkéből. Lásd a [Videóhirdetések](/retail-media-interface/integration/hu/generating-ads/banner-x-responsive/video-ads-banner-x.md) részt egy teljes hirdetésválasz-példáért, amely tartalmazza a felirat- és átiratfájlok kézbesítését.
* Videólejátszó felirattámogatással — WebVTT vagy SRT feliratsávok (pl. HTML5 `<track>` elem, vagy azzal egyenértékű natív lejátszó API).
* Engedélyezett funkció az Ön névteréhez — lépjen kapcsolatba az ügyfélkapcsolati csapatával a felirat- és átiratfeltöltések engedélyezéséhez a névterében.
* CORS konfigurálva — engedélyezze a cross-origin lekérést a következők szerinti `.vtt` fájlokhoz a Epsilon CDN tartományból HTML5 `<track>` elemek használatakor.

## Hitelesítés és biztonság

Nincs szükség további hitelesítésre. A felirat- és átiratfájlok kiszolgálása ugyanazon a CDN-en keresztül történik, mint a videóeszközöké. A hirdetésválaszban visszaküldött fájl-URL-ek nyilvánosan hozzáférhetők, ugyanazt a biztonsági modellt használva, mint a videófájlok URL-jei.

Ha a videólejátszója HTML5 `<track>` elemeket használ a következők betöltéséhez: `.vtt` fájlok, győződjön meg arról, hogy az oldal Tartalom-biztonsági házirendje (CSP) engedélyezi a lekérést a következőtől: Epsilon CDN tartomány. A CDN beállítja a megfelelő CORS-fejléceket a cross-origin `<track>` betöltéshez.

## 1. lépés: Feliratfájlok beolvasása a VAST válaszból

**Cél:** Időszinkronizált feliratfájl-URL-ek kinyerése az adm mezőben lévő VAST XML-ből a videólejátszóban való megjelenítéshez.

### Mit kell tennie

* A VAST-beolvasójában keresse a következőt: `<ClosedCaptionFiles>` elemen az egyes `<Linear>` kreatív anyag (a következőkön belül: `<MediaFiles>`).
* Minden egyes `<ClosedCaptionFile>` gyermekelemen belül a CDN URL található szöveges tartalomként.
* A(z) `type` attribútum jelzi a MIME-típust (`text/vtt` or `application/x-subrip` az SRT esetében).
* A(z) `language` attribútum jelzi a felirat nyelvét (pl. `en`).

### Példa VAST-válasz

```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áció

* Erősítse meg, hogy a VAST-értelmező kinyeri a(z) `<ClosedCaptionFile>` URL-t, ha az jelen van.
* Erősítse meg, hogy az értelmező kecsesen kezeli a(z) `<ClosedCaptionFiles>` hiányát (nem minden kampány tartalmaz feliratokat).

### Gyakori hibák

| Hiba                                 | Ok                                                                                                                                                                                       |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<ClosedCaptionFiles>` nem található | Előfordulhat, hogy a kampány nem rendelkezik jóváhagyott feliratfájllal, vagy a feliratok kézbesítése még nincs engedélyezve a környezetében. Ez a felirat nélküli kampányoknál várható. |

## 2. lépés: Írott átiratfájlok beolvasása a JSON-válaszból

**Cél:** Egyszerű szöveges átiratfájlok URL-jeinek lekérése a JSON hirdetési válaszból SEO vagy képernyőolvasó általi akadálymentesítés céljából.

### Mit kell tennie

* A(z) Banner X generálási válaszban keresse a(z) `videoTranscriptFiles` tömböt az egyes hirdetési objektumokon.
* Minden bejegyzés tartalmaz egy `videoFileId` mezőt, így megfeleltetheti az átiratokat a hozzájuk tartozó videónak.
* Az átiratok egyszerű szöveges formátumúak (`.txt`) — használja őket SEO metaadatokhoz, képernyőolvasókhoz vagy alternatív szövegek megjelenítéséhez.

### Példa JSON-válasz

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

### Validáció

* Erősítse meg, hogy a JSON-értelmező beolvassa a(z) `videoTranscriptFiles` tömböt, ha az jelen van.
* Erősítse meg a kecses kezelést, ha a tömb üres vagy hiányzik.

{% hint style="info" %}
A feliratfájlok URL-jei (a következöhöz: `.vtt`/`.srt`) csak VAST-on keresztül érhetők el, JSON-on keresztül nem. Az átiratfájlok (`.txt`) csak JSON-on keresztül érhetők el, VAST-on keresztül nem. Ez az elkülönítés a különböző felhasználási mintákat tükrözi: a feliratok a videólejátszókhoz (VAST), az átiratok pedig az oldalszintű akadálymentesítéshez (JSON) valók.\*\*
{% endhint %}

## 3. lépés: Feliratok megjelenítése a videólejátszóban

**Cél:** A zárt láncú feliratok (closed caption) megjelenítése a vásárlóknak a videó lejátszása közben.

### Mit kell tennie

* Miután beolvasta a felirat URL-jét a VAST-ból, adjon hozzá egy `<track>` elemet az HTML5 videólejátszóhoz (vagy annak megfelelőjéhez a natív lejátszó SDK-ban).
* Állítsa be a következőt: `kind="captions"`. Használja a(z) `default` attribútumot, ha azt szeretné, hogy a feliratok alapértelmezés szerint engedélyezve legyenek.
* A .srt fájlok esetében egyes lejátszók futásidőben igénylik a WebVTT formátumra való átalakítást (fűzze hozzá a következőt: `WEBVTT\n\n` és cserélje ki a vesszőt pontra az időbélyegekben).

### Példa HTML5 megvalósítás

```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áció

* Indítsa el a videót, és győződjön meg arról, hogy a feliratok megjelennek átfedésként.
* Erősítse meg, hogy a vásárló be- és kikapcsolhatja a feliratokat a lejátszó vezérlőivel.
* Erősítse meg, hogy a feliratok időszinkronban vannak a videó hangjával.

### Gyakori hibák

| Hiba                                                 | Megoldás                                                                                                                                                                  |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A feliratok nem töltődnek be (CORS-hiba a konzolban) | Gondoskodjon róla, hogy a tartalombiztonsági szabályzata (CSP) és a CORS-konfigurációja engedélyezze a lekérést a következőről: `.vtt` fájlokhoz a Epsilon CDN-tartomány. |
| A feliratok hibásan vagy üresen jelennek meg         | Ellenőrizze, hogy a fájl URL-je érvényes WebVTT-tartalmat ad-e vissza. Kérje le az URL-t közvetlenül a fájl ellenőrzéséhez.                                               |

## 4. lépés: (Opcionális) Az átirat szövegének megjelenítése

**Cél:** Akadálymentes szöveges tartalom biztosítása a videó mellett vagy alatt a képernyőolvasók és a SEO számára.

### Mit kell tennie

* Kérje le az átirat URL-jét a(z) `videoTranscriptFiles` bejegyzésből a JSON-válaszban.
* Használja az átirat szövegét akadálymentesítéshez, SEO-hoz, képernyőolvasókhoz vagy más kiskereskedő-specifikus felhasználási esetekhez.

### Példa

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

## Adatmodellek és meződefiníciók

### VAST: `ClosedCaptionFile` elem

| Attribútum / mező | Típus        | Kötelező | Leírás                    | Elfogadott értékek               |
| ----------------- | ------------ | -------- | ------------------------- | -------------------------------- |
| `type`            | string       | Igen     | A feliratfájl MIME-típusa | `text/vtt, application/x-subrip` |
| `language`        | string       | No       | A feliratsáv nyelve       | e.g. `en`                        |
| Elem szövege      | string (URL) | Igen     | A feliratfájl CDN URL-je  | HTTPS URL                        |

### JSON: `videoTranscriptFiles`

| Mező          | Típus        | Kötelező | Leírás                                                  | Elfogadott értékek |
| ------------- | ------------ | -------- | ------------------------------------------------------- | ------------------ |
| `videoFileId` | string       | Igen     | A videófájl azonosítója, amelyhez ez az átirat tartozik | UUID               |
| `format`      | string       | Igen     | Az átirat fájlformátuma                                 | `txt`              |
| `url`         | string (URL) | Igen     | Az átiratfájl CDN URL-je                                | HTTPS URL          |
| `language`    | string       | Igen     | Az átirat nyelve                                        | e.g. `en`          |

## Visszafelé kompatibilitás

Ezek a kiegészítések teljesen visszafelé kompatibilisek:

* Ha egy kampányhoz nincsenek feliratfájlok csatolva, a `<ClosedCaptionFiles>` elem teljesen kimarad a VAST-ból.
* Ha nincsenek átiratfájlok csatolva, `videoTranscriptFiles` hiányzik vagy egy üres tömb a JSON-ban.
* A meglévő integrációk, amelyek nem dolgozzák fel ezeket az új elemeket, továbbra is módosítások nélkül működnek.

## Tesztelés, sandbox és élesítés

### Sandbox / tesztkörnyezet

* Kérjen hozzáférést egy olyan teszt névtérhez, ahol a felirat- és átiratfeltöltések engedélyezve vannak (lépjen kapcsolatba a fiókkezelő csapatával).
* Töltsön fel egy tesztkampányt egy mintával `.vtt` feliratfájlt a kampányvarázslón keresztül.
* Jóváhagyja a kampányt az ellenőrzési ciklusban.
* Hívja a(z) Banner X generálási végpontot, és vizsgálja meg a VAST- és JSON-választ.

### Minta tesztesetek

| Teszt                                | Lépések                                                 | Elvárt eredmény                                                                        |
| ------------------------------------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| VAST-felirat jelen van               | Hirdetés kérése a jóváhagyott kampányhoz `.vtt` felirat | A VAST tartalmazza a következőt: `<ClosedCaptionFiles>` érvényes CDN URL-lel           |
| VAST-felirat hiányzik                | Hirdetés kérése feliratok nélküli kampányhoz            | No `<ClosedCaptionFiles>` elem a VAST-ban                                              |
| JSON átirat jelen van                | Hirdetés kérése a jóváhagyott kampányhoz `.txt` átirat  | A JSON tartalmazza a következőt: `videoTranscriptFiles` tömb a következő bejegyzéssel: |
| A feliratfájl elérhető               | Kérje le a CDN URL-t közvetlenül a VAST-válaszból       | Érvényes `WebVTT` tartalmat ad vissza WEBVTT fejléccel                                 |
| A lejátszó megjeleníti a feliratokat | Töltse be a videót és a feliratsávot a lejátszóba       | A feliratok az időpont szerint szinkronizálva jelennek meg a videó hangjával           |
| CORS a track elemhez                 | Betöltés `.vtt` keresztül `<track>` cross-origin        | Nincsenek CORS-hibák a böngészőkonzolban; a feliratok megjelennek                      |

### Élesítési ellenőrzőlista

* [ ] VAST parser kinyeri a(z) `<ClosedCaptionFile>` URL-eket, ha jelen vannak
* [ ] JSON parser beolvassa a(z) `videoTranscriptFiles[]` amikor jelen van
* [ ] Kecses visszalépés (graceful fallback), ha a feliratok vagy átiratok hiányoznak
* [ ] A videólejátszó megjeleníti a feliratokat a CDN URL-ből
* [ ] A vásárló be- és kikapcsolhatja a feliratokat
* [ ] CORS validálva a következöhöz: cross-origin `.vtt` fetch
* [ ] Az átirat szövege hozzáférhető (ha a 4. lépést hajtja végre)
* [ ] Tesztelve mindkettővel: `.vtt` és `.srt` felirat-formátumok

## Hibaelhárítás és GYIK

### `<ClosedCaptionFiles>` elem hiányzik a VAST válaszból

**Valószínű ok:** A kampány nem rendelkezik jóváhagyott feliratfájllal, vagy a felirattovábbítás nincs engedélyezve az Ön környezetében.

**Megoldás:**

* Erősítse meg, hogy a kampány rendelkezik jóváhagyott feliratfájllal (feltöltve és átment a felülvizsgálaton).
* Lépjen kapcsolatba az ügyfélszolgálati csapatával annak ellenőrzésére, hogy a funkció engedélyezve van-e a névtérben (namespace).

### CORS-hiba betöltéskor `.vtt` keresztül `<track>` elem

**Valószínű ok:** A Content Security Policy vagy a böngésző CORS-kikényszerítése blokkolja a következők cross-origin fetch műveletét: `.vtt` fájl.

**Megoldás:**

* Adja hozzá a(z) Epsilon CDN-domaint a Content Security Policy `connect-src` és `media-src` irányelveihez.
* Állítsa be a következőt: `crossorigin="anonymous"` a szülő `<video>` elemen, ha szükséges.

### A feliratok megjelennek, de nincsenek szinkronizálva a videóval

**Valószínű ok:** A feliratfájlt helytelen időbélyegekkel hozták létre, vagy a fájl egy SRT, amelyet átalakítás nélkül VTT-ként töltenek be.

**Megoldás:**

* Kérje le a feliratfájl URL-jét, és vizsgálja meg az időbélyegeket a videó lejátszásához képest.
* Ha a fájl .srt, és a lejátszója csak a .vtt formatumot támogatja, alakítsa át futásidőben (szúrja be a következőt az elejére: `WEBVTT\n\n`cserélje ki a következőt: `,` a következőre: `.` az időbélyegekben).

### Az átirat URL-je 404-es hibát ad vissza

**Valószínű ok:** A kampányt frissítették, és az átiratfájlt eltávolították, vagy CDN-terjedési késleltetés történik.

**Megoldás:**

* Kérje le újra a hirdetési választ a jelenlegi fájl URL-jének beszerzéséhez.
* Ha a probléma továbbra is fennáll, lépjen kapcsolatba a támogatási csapattal.

Amikor kapcsolatba lép a támogatási csapattal, adja meg a következőket:

* Request ID vagy correlation ID a generate hívásból
* A hirdetési kérés időbélyege (UTC)
* A(z) `<ClosedCaptionFile>` or `videoTranscriptFiles` URL, amely hibát ad
* Böngészőkonzol hiba (CORS-problémák esetén)
* Névtér (namespace) és kampányazonosító

## Kapcsolódó cikkek

* [Videóhirdetések](/retail-media-interface/integration/hu/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [Banner X hirdetések generálása különböző elhelyezésekhez](/retail-media-interface/integration/hu/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [Banner X referencia](/retail-media-interface/integration/hu/references/banner-x-reference-1.md)
* [Banner X előnézeti eszköz](/retail-media-interface/integration/hu/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/hu/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.