Questa pagina è stata tradotta dall'API Cloud Translation.

Inserire annunci con metadati di sincronizzazione dei pod di annunci

Questa guida descrive come inserire interruzioni pubblicitarie utilizzando il metodo dei metadati di temporizzazione del pod di annunci (ATM) per recuperare la tempistica e la durata precise delle interruzioni pubblicitarie, inclusi gli annunci pre-roll.

Per inserire annunci pre-roll e gestire il ritorno ai contenuti dopo le interruzioni pubblicitarie mid-roll, ti consigliamo di chiamare le seguenti API:

API Ad pod Timing Metadata (ATM): esegui query sui risultati della decisione del pod di annunci, incluse le durate degli annunci e delle schermate.
Endpoint del segmento dell'annuncio: richiedi segmenti di annunci o slate con l'opzione di terminare il pod pubblicitario corrente.

Se vuoi, per gli eventi di live streaming con un'alta concorrenza, ti consigliamo di chiamare l'API Early Ad Break Notification (EABN) per pianificare le decisioni sugli annunci prima dell'inizio dell'interruzione pubblicitaria.

Prerequisiti

Per iniziare, devi configurare un evento in live streaming per il tipo di inserimento dinamico degli annunci (DAI) Reindirizzamento pubblicazione pod. Scegli uno dei seguenti metodi:

UI di Ad Manager: configura un live streaming per DAI.
API Ad Manager:utilizza una libreria client (opzioni disponibili) per chiamare il metodo LiveStreamEventService.createLiveStreamEvents. Imposta il parametro LiveStreamEvent.dynamicAdInsertionType su POD_SERVING_REDIRECT.

Recuperare lo stream di contenuti

Quando un utente seleziona un evento di live streaming, l'app client invia una richiesta di streaming a Google Ad Manager. Nella risposta dello stream, l'app estrae l'ID sessione DAI di Google e i metadati da includere nella richiesta del manifest dello stream.

L'esempio seguente trasmette un ID sessione Google DAI a un manipolatore di manifest:

https://MANIFEST_MANIPULATOR_URL/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY

Quando elabori la richiesta di riproduzione dei contenuti video, memorizza l'ID sessione Google DAI e CUSTOM_ASSET_KEY dalla richiesta per prepararti all'inserimento degli annunci.

Recuperare i metadati di sincronizzazione del pod di annunci

Per recuperare la tempistica del pod di annunci:

Genera un token HMAC.
Chiama l'API ATM con il token HMAC.

Genera un token HMAC firmato

Per autenticare le tue richieste, segui questi passaggi:

Crea una stringa token concatenando i seguenti parametri in ordine alfabetico, separati da una tilde ~:

Parametro	Obbligatorio o facoltativo	Descrizione
`ad_break_id`	Obbligatorio	Una stringa specificata per identificare l'interruzione pubblicitaria, ad esempio `ad-break-1`. Per gli annunci pre-roll, utilizza `preroll`.
`custom_asset_key`	Obbligatorio	La chiave asset personalizzata dell'evento di live streaming.
`cust_params`	Facoltativo	Parametri di targeting personalizzato. Per maggiori dettagli, consulta l'articolo Fornire parametri di targeting alla riproduzione in streaming.
`exp`	Obbligatorio	L'ora in cui questo token scade, misurata come il numero totale di secondi trascorsi dall'epoca Unix.
`network_code`	Obbligatorio	Il tuo codice di rete Google Ad Manager. Per maggiori dettagli, vedi Trovare informazioni sull'account Ad Manager.
`pd`	Obbligatorio	La durata dell'interruzione pubblicitaria in millisecondi. Per gli annunci pre-roll, Google DAI esegue l'override di questo parametro con le impostazioni dell'evento di live streaming.
`scte35`	Facoltativo	Segnale SCTE-35 con codifica Base64. Verifica che il segnale sia corretto. Se non è corretto, nella risposta viene inviato un messaggio all'intestazione HTTP `X-Ad-Manager-Dai-Warning` e l'indicatore viene comunque propagato per creare un'interruzione pubblicitaria. Per maggiori dettagli sugli indicatori di interruzione pubblicitaria supportati, consulta Integrazione HLS.

Scarica la chiave di autenticazione Google DAI di tipo HMAC. Per maggiori dettagli, consulta Autenticare le richieste di video stream DAI.
Utilizza la chiave HMAC scaricata per generare la firma SHA256 della stringa del token.
Concatena la stringa del token e la firma generata.
Applica la codifica URL alla stringa concatenata. La stringa codificata è il token HMAC firmato per l'autenticazione delle richieste dell'API Ad pod Timing Metadata (ATM).

Il seguente esempio genera un token HMAC firmato per gli annunci pre-roll:

custom_asset_key="CUSTOM_ASSET_KEY"
exp="1750700000" # Expired on Mon Jun 23 2025 13:33:20 GMT-0400 (Eastern Daylight Time)
network_code="NETWORK_CODE"
ad_break_id="preroll"
pd="0" # Pod duration value is overridden by the livestream event settings.

# The HMAC authentication key associated with your livestream event in Google Ad Manager.
secret_key="24E96382584C328087546B0E8454F26158564E8466FD2BE3D8A996B38445876C"

# Concatenate the parameters, keep the parameters alphabetically ordered by name.
token_string="ad_break_id=${ad_break_id}~custom_asset_key=${custom_asset_key}~exp=${exp}~network_code=${network_code}~pd=${pd}"

# Calculate the SHA256 signature of the token_string.
hmac_signature=$(echo -n "$token_string" | openssl dgst -sha256 -hmac "$secret_key" | awk '{print $2}')

# Concatenate the token string and the signature.
signed_token="${token_string}~hmac=${hmac_signature}"

url_encode() {
    local string="${1}"
    local strlen=${#string}
    local encoded=""
    local pos c
    for (( pos=0 ; pos<strlen ; pos++ )); do
        c=${string:$pos:1}
        case "$c" in
            [-_.~a-zA-Z0-9] ) o="${c}" ;;
            *   ) printf -v o '%%%02x' "'$c"
        esac
        encoded+="${o}"
    done
    echo "${encoded}"
}

# Apply URL encoding to the concatenated string.
url_encoded_signed_token=$(url_encode "$signed_token")

echo "Signed HMAC token:"
echo "${url_encoded_signed_token}"

# Example output:
# ad_break_id%3Dpreroll~custom_asset_key%3DiYdOkYZdQ1KFULXSN0Gi7g~exp%3D1489680000~network_code%3D21775744923~pd%3D180000~pod_id%3D5~hmac%3D24E96382584C328087546B0E8454F26158564E8466FD2BE3D8A996B38445876C

Richiedere i metadati di temporizzazione per gli annunci pre-roll

Verifica le impostazioni del pre-roll per il tuo evento live streaming utilizzando le seguenti opzioni:

Per recuperare i risultati della decisione relativa all'annuncio pre-roll, invia una richiesta all'API ATM.

L'esempio seguente invia una richiesta ATM per gli annunci pre-roll:

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=preroll&auth-token=your_signed_HMAC_token"

Richiedere i metadati di temporizzazione per gli annunci mid-roll

Per recuperare i metadati del pod di annunci per i mid-roll:

Analizza il manifest del live streaming per trovare i marcatori pubblicitari che contengono la tempistica e la durata di ogni interruzione pubblicitaria mid-roll.
Chiama l'endpoint dell'API ATM per richiedere la durata esatta del pod pubblicitario e della schermata. L'API restituisce un oggetto JSON con i risultati della decisione del pod di annunci.

L'esempio seguente esegue una richiesta ATM per gli annunci mid-roll:

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=AD_BREAK_ID&pd=AD_BREAK_DURATION&auth-token=your_signed_HMAC_token"

Se l'operazione va a buon fine, viene visualizzato un output simile al seguente oggetto JSON:

{
  "status": "final",
  "ads": [
    {
      "duration_ms": 5046,
      "variants": {
        "devrel1428000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        },
        "devrel1928000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        }
      }
    }
  ],
  "slate": {
    "duration_ms": 0,
    "variants": {
      "devrel1428000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      },
      "devrel1928000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      }
    }
  }
}

Unire gli annunci nel manifest dei contenuti

Le sezioni seguenti illustrano come modificare il manifest del live streaming e aggiungere i segmenti pubblicitari.

Identificare i segmenti di interruzione pubblicitaria e inserire le discontinuità

Durante l'elaborazione di ogni manifest delle varianti, identifica i tag EXT-X-CUE-IN e EXT-X-CUE-OUT nel flusso, che indicano l'inizio e la fine di una pausa pubblicitaria.

Sostituisci i tag EXT-X-CUE-IN e EXT-X-CUE-OUT con gli elementi EXT-X-DISCONTINUITY per consentire al video player client di passare da contenuti e annunci.

Il seguente file manifest di esempio sostituisce i tag EXT-X-CUE-IN e EXT-X-CUE-OUT:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXT-X-CUE-OUT:15.000
#EXTINF:5.000,
contentorigin.com/3.ts
#EXTINF:5.000,
contentorigin.com/4.ts
#EXTINF:5.000,
contentorigin.com/5.ts
#EXT-X-CUE-IN
#EXTINF:5.000,
contentorigin.com/6.ts
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

L'esempio seguente mostra un manifest sostituito:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXTINF:5.000,
#EXT-X-DISCONTINUITY
{... Insert ad segments here ...}
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
contentorigin.com/6.mp4
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

I segmenti degli annunci DAI di Google non sono criptati. Se i tuoi contenuti sono criptati, rimuovi la crittografia inserendo l'elemento EXT-X-KEY:METHOD=NONE prima del primo segmento pubblicitario di ogni interruzione pubblicitaria. Al termine dell'interruzione pubblicitaria, aggiungi di nuovo la crittografia inserendo un EXT-X-KEY appropriato.

Tieni traccia dell'ora di inizio, della durata e dell'indice della prossima interruzione pubblicitaria.

Creare URL di segmenti pubblicitari

Sostituisci i segmenti di contenuti tra i tag EXT-X-DISCONTINUITY con gli URL per ogni segmento di annunci. Per determinare il numero di segmenti pubblicitari da inserire, utilizza ads.segment_durations.values fornito nella risposta JSON dell'API ATM.

Per terminare un pod di annunci in anticipo quando viene rilevato un tag EXT-X-CUE-IN, aggiungi il parametro d= all'URL dell'ultimo segmento dell'annuncio. Questo parametro accorcia il segmento per evitare di influire sulla cronologia del video player del client.

L'esempio seguente assembla un URL del segmento dell'annuncio pre-roll nel manifest. Tieni presente che i segmenti di annunci utilizzano un indice basato su zero:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/preroll/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

L'esempio seguente assembla un URL del segmento pubblicitario mid-roll nel manifest:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

L'esempio seguente inserisce segmenti pubblicitari nel manifest:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.00,
contentorigin.com/1.ts
#EXTINF:5.00,
contentorigin.com/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/1.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/2.ts?stream_id=SESSION_ID
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
contentorigin.com/6.mp4
#EXTINF:5.00,
contentorigin.com/7.mp4
#EXTINF:5.00,
contentorigin.com/8.mp4

Creare segmenti di slate

Per colmare il divario tra l'annuncio e i contenuti, inserisci segmenti di slate. Utilizza l'array slates.segment_durations.values della risposta JSON dell'API ATM per determinare la durata di ogni segmento della schermata. Ripeti la sequenza di durate dei segmenti in base alle necessità per riempire l'intera interruzione pubblicitaria.

L'esempio seguente assembla un segmento di slate:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/slate/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

Il slate/0 nell'esempio rappresenta il numero di iterazione della scheda. Fai riferimento alla compatibilità e alla funzionalità di memorizzazione nella cache del video player client per determinare se iniziare da 0 e incrementare questo numero per ogni ciclo della schermata, o mantenerlo a 0 per tutte le iterazioni.

Gestire il ritorno ai contenuti

Dopo aver inserito tutti i segmenti del pod di annunci, scegli uno dei seguenti metodi per tornare al flusso di contenuti:

Metodo	Descrizione	Effetti sul video player client
Riempi con i segmenti della scheda	Inserisce i segmenti della lavagna e li ripete in loop. Riempie la durata e inserisce gli elementi `EXT-X-DISCONTINUITY` tra ogni iterazione della scheda.	Nessun effetto. Il video player torna ai contenuti senza alterare la sequenza temporale.
Riallineare con un singolo segmento di blocco	Inserisce un singolo segmento di lavagna. Utilizza il parametro `d=` per riempire la durata fino all'inizio dei contenuti.	Nessun effetto. Il video player torna ai contenuti senza alterare la sequenza temporale.
Reso immediato	Inserisci segmenti di contenuti.	La sequenza temporale del video player viene modificata. Il video player del client deve gestire la sequenza temporale modificata.

(Facoltativo) Pianifica un'interruzione pubblicitaria

Per migliorare il tasso di riempimento, invia una notifica di interruzione pubblicitaria anticipata (EABN) con la durata del pod pubblicitario, i parametri di targeting personalizzati e i dati dei segnali SCTE-35. Per maggiori dettagli, vedi Inviare notifiche di interruzione pubblicitaria anticipata.