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

# Sottotitoli dei video Banner X

## Panoramica

La Epsilon Retail Media piattaforma supporta file di sottotitoli e trascrizioni per le Banner X campagne video. Gli inserzionisti caricano file di sottotitoli (`.vtt`, `.srt`) e file di trascrizione (`.txt`) insieme ai loro asset video. La tua integrazione utilizza questi URL di file dalla risposta pubblicitaria e riproduce i sottotitoli nel tuo lettore video.

Questa integrazione ti aiuta a soddisfare i requisiti di accessibilità come l'European Accessibility Act (EAA), che impone sottotitoli controllabili dall'utente sui contenuti video rivolti al pubblico.

* I file di sottotitoli sono tracce di sottotitoli sincronizzate con il tempo per il tuo lettore video.
* I file di trascrizione sono rappresentazioni in testo semplice del contenuto audio del video per l'uso da parte di SEO e lettori di schermo.

Questa guida copre:

* Come i file di sottotitoli e trascrizione appaiono nelle risposte pubblicitarie VAST e JSON
* Struttura dell'elemento `<ClosedCaptionFile>` VAST 4.3
* struttura dell'array `videoTranscriptFiles[]` JSON
* Come riprodurre i sottotitoli utilizzando gli URL CDN forniti
* Test e validazione

### Modello di distribuzione

Gli URL dei file di sottotitoli (`.vtt` / `.srt`) sono distribuiti solo tramite VAST, non JSON.\
Gli URL dei file di trascrizione (`.txt`) sono distribuiti solo tramite JSON, non VAST.\
I sottotitoli vengono utilizzati dal tuo lettore video; le trascrizioni vengono utilizzate a livello di pagina.

## Flusso di integrazione

I file di sottotitoli e trascrizione seguono lo stesso percorso di distribuzione degli asset video. Non sono richieste chiamate API aggiuntive oltre alla tua Banner X richiesta pubblicitaria esistente.

1. Un inserzionista carica file video, di sottotitoli e di trascrizione tramite la procedura guidata della campagna.
2. I file vengono convalidati, archiviati e serviti tramite CDN.
3. La tua richiesta pubblicitaria Banner X esistente restituisce gli URL dei sottotitoli in VAST e gli URL delle trascrizioni in JSON.
4. Il tuo lettore video legge l'URL del file di sottotitoli e riproduce i sottotitoli.
5. La tua pagina visualizza opzionalmente il testo della trascrizione per l'accessibilità o la SEO.

## Tipi di file supportati

| Asset        | Formati                          | Dimensione massima                                                      |
| ------------ | -------------------------------- | ----------------------------------------------------------------------- |
| Sottotitoli  | `.vtt` (WebVTT), `.srt` (SubRip) | Configurabile per standard di contenuto del retailer (in genere 1–4 MB) |
| Trascrizione | `.txt` (testo semplice)          | Configurabile per standard di contenuto del retailer (in genere 1–4 MB) |

I file vengono serviti così come sono; la piattaforma non converte i formati. Il tuo lettore video è responsabile della riproduzione dei sottotitoli.

## Requisiti preliminari

Prima di integrare sottotitoli e trascrizioni, conferma quanto segue:

* Integrazione video Banner X esistente — utilizzi già `<MediaFiles>` dal tag VAST nel campo adm. Vedi [Annunci video](/retail-media-interface/integration/it/generating-ads/banner-x-responsive/video-ads-banner-x.md) per un esempio completo di risposta pubblicitaria che include la distribuzione di file di sottotitoli e trascrizione.
* Lettore video con supporto per i sottotitoli — tracce di sottotitoli WebVTT o SRT (ad es. elemento HTML5 `<track>` , o API del lettore nativo equivalente).
* Funzionalità abilitata per il tuo namespace — contatta il tuo team account per abilitare il caricamento di sottotitoli e trascrizioni per il tuo namespace.
* CORS configurato — consenti il recupero cross-origin dei file `.vtt` dal dominio CDN Epsilon quando utilizzi elementi HTML5 `<track>` .

## Autenticazione e sicurezza

Non è richiesta alcuna autenticazione aggiuntiva. I file di sottotitoli e trascrizione vengono serviti tramite la stessa CDN degli asset video. Gli URL dei file restituiti nella risposta pubblicitaria sono accessibili pubblicamente, utilizzando lo stesso modello di sicurezza degli URL dei file video.

Se il tuo lettore video utilizza elementi HTML5 `<track>` per caricare file `.vtt` , assicurati che la Content Security Policy della tua pagina consenta il recupero dal dominio CDN Epsilon . La CDN imposta le intestazioni CORS appropriate per il caricamento `<track>` cross-origin.

## Passaggio 1: Analizza i file dei sottotitoli dalla risposta VAST

**Scopo:** Recupera gli URL dei file di sottotitoli sincronizzati nel tempo dall'XML VAST nel campo adm per la riproduzione nel tuo lettore video.

### Cosa devi fare

* Nel tuo parser VAST, cerca l'elemento `<ClosedCaptionFiles>` all'interno di ciascun `<Linear>` materiale creativo (all'interno di `<MediaFiles>`).
* Ciascun `<ClosedCaptionFile>` elemento figlio contiene l'URL CDN come contenuto testuale.
* L' `type` attributo indica il tipo MIME (`text/vtt` or `application/x-subrip` per SRT).
* L' `language` attributo indica la lingua dei sottotitoli (ad es. `en`).

### Esempio di risposta 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>
```

### Validazione

* Conferma che il tuo parser VAST estragga il `<ClosedCaptionFile>` URL quando presente.
* Conferma che il tuo parser gestisca in modo corretto l'assenza di `<ClosedCaptionFiles>` (non tutte le campagne includono i sottotitoli).

### Errori comuni

| Errore                             | Causa                                                                                                                                                                                                                  |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<ClosedCaptionFiles>` non trovato | La campagna potrebbe non avere un file di sottotitoli approvato, oppure l'erogazione dei sottotitoli non è ancora abilitata per il tuo ambiente. Questo è il comportamento previsto per le campagne senza sottotitoli. |

## Passaggio 2: Esegui il parsing dei file di trascrizione dalla risposta JSON

**Scopo:** Recupera gli URL dei file di trascrizione in testo semplice dalla risposta pubblicitaria JSON per il SEO o per l'accessibilità degli screen reader.

### Cosa devi fare

* In Banner X risposta di generazione, cerca il `videoTranscriptFiles` array su ciascun oggetto annuncio.
* Ogni voce include un `videoFileId` in modo da poter abbinare le trascrizioni al video corrispondente.
* Le trascrizioni sono in testo semplice (`.txt`) — utilizzale per i metadati SEO, gli screen reader o la visualizzazione di testo alternativo.

### Esempio di risposta JSON

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

### Validazione

* Conferma che il tuo parser JSON legga il `videoTranscriptFiles` array quando presente.
* Conferma la gestione corretta quando l'array è vuoto o assente.

{% hint style="info" %}
Gli URL dei file dei sottotitoli (per `.vtt`/`.srt`) vengono forniti solo tramite VAST, non JSON. I file di trascrizione (`.txt`) vengono forniti solo tramite JSON, non VAST. Questa separazione riflette i diversi modelli di fruizione: i sottotitoli sono per i lettori video (VAST), le trascrizioni sono per l'accessibilità a livello di pagina (JSON).\*\*
{% endhint %}

## Passaggio 3: Rendering dei sottotitoli nel lettore video

**Scopo:** Mostra i sottotitoli agli acquirenti durante la riproduzione del video.

### Cosa devi fare

* Dopo aver eseguito il parsing dell'URL dei sottotitoli da VAST, aggiungi un `<track>` elemento al tuo lettore video HTML5 (o equivalente nel tuo SDK del lettore nativo).
* Imposta `kind="captions"`. Utilizza il `default` attributo se desideri che i sottotitoli siano abilitati per impostazione predefinita.
* Per i file .srt, alcuni lettori richiedono la conversione in WebVTT a runtime (anteponi `WEBVTT\n\n` e sostituisci la virgola con il punto nei timestamp).

### Esempio di implementazione 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>
```

### Validazione

* Riproduci il video e conferma che i sottotitoli appaiano in sovrapposizione.
* Conferma che l'acquirente possa attivare/disattivare i sottotitoli tramite i controlli del lettore.
* Conferma che i sottotitoli siano sincronizzati negli orari con l'audio del video.

### Errori comuni

| Errore                                                    | Soluzione                                                                                                                                    |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| I sottotitoli non si caricano (errore CORS nella console) | Assicurati che la tua Content Security Policy e la configurazione CORS consentano il recupero di `.vtt` dal dominio CDN Epsilon dominio CDN. |
| I sottotitoli appaiono illeggibili o vuoti                | Verifica che l'URL del file restituisca contenuto WebVTT valido. Recupera l'URL direttamente per ispezionare il file.                        |

## Passaggio 4: (Opzionale) Visualizza il testo della trascrizione

**Scopo:** Fornisci contenuto testuale accessibile accanto o sotto il video per gli screen reader e per il SEO.

### Cosa devi fare

* Recupera l'URL della trascrizione dal `videoTranscriptFiles` voce nella risposta JSON.
* Utilizza il testo della trascrizione per l'accessibilità, il SEO, gli screen reader o altri casi d'uso specifici del rivenditore.

### Esempio

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

## Modelli di dati e definizioni dei campi

### VAST: `ClosedCaptionFile` elemento

| Attributo / campo   | Tipo          | Obbligatorio | Descrizione                          | Valori accettati                 |
| ------------------- | ------------- | ------------ | ------------------------------------ | -------------------------------- |
| `type`              | stringa       | Sì           | Tipo MIME del file dei sottotitoli   | `text/vtt, application/x-subrip` |
| `language`          | stringa       | No           | Lingua della traccia dei sottotitoli | e.g. `en`                        |
| Testo dell'elemento | stringa (URL) | Sì           | URL CDN del file dei sottotitoli     | URL HTTPS                        |

### JSON: `videoTranscriptFiles`

| Campo         | Tipo          | Obbligatorio | Descrizione                                            | Valori accettati |
| ------------- | ------------- | ------------ | ------------------------------------------------------ | ---------------- |
| `videoFileId` | stringa       | Sì           | ID del file video a cui appartiene questa trascrizione | UUID             |
| `format`      | stringa       | Sì           | Formato del file della trascrizione                    | `txt`            |
| `url`         | stringa (URL) | Sì           | URL CDN del file della trascrizione                    | URL HTTPS        |
| `language`    | stringa       | Sì           | Lingua della trascrizione                              | e.g. `en`        |

## Retrocompatibilità

Queste aggiunte sono completamente retrocompatibili:

* Se a una campagna non è allegato alcun file di sottotitoli, l' `<ClosedCaptionFiles>` elemento viene del tutto omesso dal VAST.
* Se non è allegato alcun file di trascrizione, `videoTranscriptFiles` è assente o è un array vuoto nel JSON.
* Le integrazioni esistenti che non analizzano questi nuovi elementi continuano a funzionare senza modifiche.

## Test, sandbox e go-live

### Ambiente sandbox / di test

* Richiedi l'accesso a un namespace di test con il caricamento di sottotitoli e trascrizioni abilitato (contatta il tuo team di account).
* Carica una campagna di test con un file di `.vtt` sottotitoli di esempio tramite la procedura guidata della campagna.
* Approva la campagna attraverso il ciclo di revisione.
* Chiama l' Banner X endpoint di generazione e ispeziona la risposta VAST e JSON.

### Casi di test di esempio

| Test                              | Passaggi                                                                | Risultato previsto                                                               |
| --------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Sottotitolo VAST presente         | Richiedi l'annuncio per la campagna con sottotitolo `.vtt` approvato    | VAST contiene `<ClosedCaptionFiles>` con URL CDN valido                          |
| Sottotitolo VAST assente          | Richiedi l'annuncio per la campagna senza sottotitoli                   | No `<ClosedCaptionFiles>` elemento nel VAST                                      |
| Trascrizione JSON presente        | Richiedi l'annuncio per la campagna con sottotitolo `.txt` trascrizione | JSON contiene `videoTranscriptFiles` array con voce                              |
| File dei sottotitoli accessibile  | Recupera l'URL CDN direttamente dalla risposta VAST                     | Restituisce un valido `WebVTT` contenuto con intestazione WEBVTT                 |
| Il player riproduce i sottotitoli | Carica il video e la traccia dei sottotitoli nel tuo player             | I sottotitoli vengono visualizzati sincronizzati con l'audio del video           |
| CORS per l'elemento track         | Carica `.vtt` tramite `<track>` cross-origin                            | Nessun errore CORS nella console del browser; i sottotitoli vengono visualizzati |

### Checklist per la messa in onda

* [ ] Il parser VAST estrae `<ClosedCaptionFile>` gli URL quando presenti
* [ ] Il parser JSON legge `videoTranscriptFiles[]` quando presenti
* [ ] Gestione elegante dei casi di errore quando sottotitoli o trascrizioni sono assenti
* [ ] Il lettore video visualizza i sottotitoli dall'URL della CDN
* [ ] L'acquirente può attivare/disattivare i sottotitoli
* [ ] CORS convalidato per il fetch `.vtt` cross-origin
* [ ] Testo della trascrizione accessibile (se si implementa il Passaggio 4)
* [ ] Testato sia con `.vtt` che con `.srt` i formati di sottotitoli

## Risoluzione dei problemi e FAQ

### `<ClosedCaptionFiles>` elemento mancante dalla risposta VAST

**Causa probabile:** La campagna non ha un file di sottotitoli approvato, oppure l'erogazione dei sottotitoli non è abilitata nel tuo ambiente.

**Soluzione:**

* Conferma che la campagna abbia un file di sottotitoli approvato (caricato e che ha superato la revisione).
* Contatta il tuo team di supporto per verificare che la funzionalità sia abilitata per il tuo namespace.

### Errore CORS durante il caricamento dell'elemento `.vtt` tramite `<track>` elemento

**Causa probabile:** le impostazioni della Content Security Policy o il blocco CORS del browser impediscono il recupero cross-origin del `.vtt` .

**Soluzione:**

* Aggiungi il dominio CDN di Epsilon alle direttive della tua `connect-src` che con `media-src` Content Security Policy.
* Imposta `crossorigin="anonymous"` sull'elemento `<video>` padre se richiesto.

### I sottotitoli vengono visualizzati ma non sono sincronizzati con il video

**Causa probabile:** Il file dei sottotitoli è stato creato con timestamp errati, oppure il file è un SRT caricato come VTT senza conversione.

**Soluzione:**

* Recupera l'URL del file dei sottotitoli e ispeziona i timestamp rispetto alla riproduzione del video.
* Se il file è .srt e il tuo lettore supporta solo .vtt, convertilo al momento dell'esecuzione (anteponi `WEBVTT\n\n`, sostituisci `,` con `.` nei timestamp).

### L'URL della trascrizione restituisce 404

**Causa probabile:** La campagna è stata aggiornata e il file della trascrizione è stato rimosso, oppure si tratta di un ritardo di propagazione della CDN.

**Soluzione:**

* Effettua nuovamente il fetch della risposta dell'annuncio per ottenere l'URL del file corrente.
* Se il problema persiste, contatta il supporto.

Quando contatti il supporto, includi:

* ID richiesta o ID di correlazione dalla chiamata generate
* Timestamp (UTC) della richiesta dell'annuncio
* L' `<ClosedCaptionFile>` or `videoTranscriptFiles` URL che restituisce l'errore
* Errore della console del browser (per problemi CORS)
* Namespace e ID campagna

## Articoli correlati

* [Annunci video](/retail-media-interface/integration/it/generating-ads/banner-x-responsive/video-ads-banner-x.md)
* [Genera annunci Banner X per diversi posizionamenti](/retail-media-interface/integration/it/generating-ads/banner-x-responsive/requesting-banner-x-ads.md)
* [Riferimento per Banner X](/retail-media-interface/integration/it/references/banner-x-reference-1.md)
* [Anteprima di Banner X](/retail-media-interface/integration/it/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/it/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.