Utilizza un'integrazione personalizzata

Prima di iniziare

Questo documento riguarda solo le istruzioni di riproduzione in assenza dell'SDK IMA DAI.

Assicurati di aver già completato i passaggi descritti in Integrare Google Ad Manager (GAM) con gli asset VOD in precedenza.

Se l'SDK IMA non è disponibile per la piattaforma scelta, la tua applicazione dovrà chiamare le API richieste e attivare le verifiche dei contenuti multimediali degli annunci.

Per farlo, ti serviranno le seguenti informazioni:

Località La regione Google Cloud in cui è stata creata la configurazione attiva:
LOCATION
Numero progetto Il numero del progetto Google Cloud che utilizza l'API Video Stitcher:
PROJECT_NUMBER
Token OAuth Il token OAuth a breve durata di un account di servizio con il ruolo utente Video Stitcher: 
OAUTH_TOKEN
Scopri di più sulla creazione di token OAuth a vita breve.
Codice rete Il codice di rete Ad Manager per la richiesta di annunci:
NETWORK_CODE
ID configurazione VOD L'ID di configurazione VOD specificato durante la creazione dell'evento stream VOD:
VOD_CONFIG_ID

Inviare una richiesta di registrazione dello stream ad Ad Manager

Invia una richiesta POST all'endpoint di registrazione dello stream. In cambio, ricevi una risposta JSON contenente l'ID stream da inviare al tuo server di manipolazione del manifest e agli endpoint dell'API Pod Serving associati.

endpoint API

POST: /ondemand/pods/api/v1/network/NETWORK_CODE/stream_registration
Host: dai.google.com
Content-Type: application/json

Parametri del percorso

NETWORK_CODE Il tuo codice di rete Google Ad Manager 360

Parametri del corpo con codifica JSON

targeting_parameters
Un insieme di parametri di targeting facoltativi codificati in JSON.

JSON della risposta

media_verification_url L'URL di base per eseguire il ping degli eventi di monitoraggio della riproduzione. Un URL di verifica dei contenuti multimediali completo viene formato aggiungendo un ID evento annuncio a questo URL di base. MEDIA_VERIFICATION_URL
metadata_url L'URL per richiedere i metadati dei pod di annunci. METADATA_URL
stream_id La stringa utilizzata per identificare la sessione di streaming corrente. STREAM_ID
valid_for Il tempo rimanente fino alla scadenza della sessione di streaming corrente, in formato dhms (giorni, ore, minuti, secondi). Ad esempio, 2h0m0.000s rappresenta una durata di 2 ore.
valid_until L'ora di scadenza della sessione di streaming corrente, come stringa data/ora ISO 8601 nel formato yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.

Richiesta di esempio (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

Risposta di esempio

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

In caso di errori, vengono restituiti codici di errore HTTP standard senza testo della risposta JSON.

Analizza la risposta JSON e memorizza i valori pertinenti.

Generare una sessione VOD di Cloud Video Stitcher

Invia una richiesta POST all'endpoint di registrazione della sessione VOD. In cambio, ricevi una risposta JSON contenente l'URI manifest dello stream e i metadati relativi a interruzioni pubblicitarie, annunci ed eventi correlati agli annunci.

endpoint API

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

Parametri del percorso

PROJECT_NUMBER Il numero del tuo progetto Google Cloud.
LOCATION La tua regione Google Cloud.
NETWORK CODE Il tuo codice di rete Google Ad Manager 360.

Parametri del corpo con codifica JSON

vodConfig Una stringa contenente il numero del progetto, la località e l'ID configurazione VOD nel seguente formato:
projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
adTracking Imposta su "CLIENT" per attivare il monitoraggio lato client.
gamSettings Un oggetto contenente il codice di rete e l'ID stream con il seguente formato: 
{
  "networkCode":"NETWORK_CODE",
  "streamId":"STREAM_ID"
}

JSON della risposta

name Il nome della sessione VOD, contenente l'ID sessione.
playUri L'URI del manifest dello stream unito da caricare nel video player per la riproduzione.
SESSION_PLAYBACK_URI
adTracking Lo stesso valore adTracking inviato all'API nel corpo della richiesta.
vodConfig La stessa stringa vodConfig inviata all'API nel corpo della richiesta.
gamSettings Lo stesso oggetto gamSettings inviato all'API nel corpo della richiesta.

Richiesta di esempio (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

Risposta di esempio

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

Una volta ricevuta la risposta, puoi riprodurre il live streaming con annunci uniti facendo riferimento all'URI nel campo playUri dell'oggetto risposta.

Richiedere i metadati dei pod di annunci da Ad Manager

Invia una richiesta GET all'indirizzo metadata_url che hai ricevuto quando hai registrato il tuo stream con Ad Manager. Questo passaggio deve essere eseguito dopo aver ricevuto il manifest unito dall'URI di riproduzione.

A tua volta ricevi un oggetto JSON che descrive le interruzioni pubblicitarie, gli annunci e gli eventi pubblicitari dello stream.

Endpoint API

GET: METADATA_URL
Host: dai.google.com

JSON della risposta

tags Un insieme di coppie chiave-valore che descrivono gli eventi relativi ai media degli annunci che si verificheranno all'interno dello stream. Ogni chiave è costituita dai primi 17 caratteri di un ID elemento multimediale dell'annuncio che verrà visualizzato nei metadati ID3 dello stream o, nel caso degli eventi "progress", dall'intero ID elemento multimediale dell'annuncio. Ogni valore è un oggetto con le seguenti proprietà:
  • ad: l'ID dell'annuncio contenente l'evento relativo ai media dell'annuncio.
  • ad_break_id: l'ID dell'interruzione pubblicitaria contenente l'evento media dell'annuncio.
  • type: il tipo di evento relativo ai media dell'annuncio. I valori possono essere uno dei seguenti:
    • start: l'annuncio è iniziato
    • firstquartile: l'annuncio è completato per il 25%.
    • midpoint: l'annuncio è completato al 50%.
    • thirdquartile: l'annuncio è completato al 75%.
    • complete: l'annuncio è terminato.
    • progress: attivato ogni secondo durante la riproduzione di un annuncio.
ads Un insieme di coppie chiave-valore che descrivono gli annunci da mostrare all'interno dello stream. Ogni chiave è un ID annuncio. Ogni valore è un oggetto con le seguenti proprietà:
  • ad_break_id: l'ID dell'interruzione pubblicitaria contenente l'evento media dell'annuncio.
  • position: la posizione dell'annuncio all'interno dell'interruzione pubblicitaria. Tieni presente che il primo annuncio in un'interruzione ha la posizione 1.
  • duration: la durata dell'annuncio in secondi con virgola mobile.
  • title: il titolo dell'annuncio, come definito in VAST.
  • description: la descrizione dell'annuncio, come definito nel VAST.
  • ad_system: il sistema di annunci, come definito in VAST.
  • ad_system: l'ID annuncio, come definito in VAST.
  • ad_system: l'ID creatività, come definito in VAST.
  • clickthrough_url: l'URL da aprire quando un utente interagisce con l'annuncio.
  • universal_ad_id: un oggetto che rappresenta l'ID annuncio universale, come definito in VAST.
ad_breaks Un insieme di coppie chiave-valore che descrivono le interruzioni pubblicitarie che si verificano all'interno dello stream. Ogni chiave è un ID interruzione pubblicitaria. Ogni valore è un oggetto con le seguenti proprietà:
  • type: il tipo di interruzione pubblicitaria. I valori possono essere uno dei seguenti:
    • pre: rappresenta un annuncio pre-roll.
    • mid: rappresenta un annuncio mid-roll.
    • post: rappresenta un annuncio post-roll.
  • duration: la durata dell'interruzione pubblicitaria in secondi con virgola mobile.
  • expected_duration: la durata prevista dell'interruzione pubblicitaria in secondi in virgola mobile.
  • ads: il numero di annunci contenuti nell'interruzione pubblicitaria.

Richiesta di esempio (cURL)

curl METADATA_URL

Esempio di risposta JSON

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

Memorizza questi valori da associare agli eventi dei metadati con temporizzazione all'interno dello stream video.

Ascolta gli eventi ID3 e monitora gli eventi di riproduzione

Per verificare che siano avvenuti eventi specifici in uno stream video, segui questi passaggi per gestire gli eventi ID3:

  1. Memorizza gli eventi multimediali in una coda, salvando ogni ID media insieme al relativo timestamp, se visualizzato dal player.
  2. A ogni aggiornamento della data e dell'ora dal player o a una frequenza impostata (consigliata 500 ms), controlla la coda di eventi multimediali per gli eventi riprodotti di recente confrontando i timestamp degli eventi con il cursore di riproduzione.
  3. Per gli eventi multimediali di cui confermi la riproduzione, controlla il tipo cercando l'ID media nei tag di interruzione pubblicitaria archiviati. Tieni presente che l'oggetto tag interruzione annunci contiene solo una versione troncata dell'ID media, limitata alle prime 10 cifre dopo il prefisso google_, pertanto non esiste una corrispondenza diretta tra le chiavi e gli ID di verifica dei contenuti multimediali ID3 nell'oggetto tag. Questo serve per impedire l'invio di ping di verifica degli eventi prima dell'arrivo dell'evento ID3. Per generare l'URL completo di verifica dei contenuti multimediali di un evento annuncio, aggiungere l'ID evento annuncio completo al valore media_verification_url della risposta alla creazione dello stream.
  4. Utilizza gli eventi "progress" per monitorare se un utente si trova all'interno di un'interruzione pubblicitaria. Non inviare questi eventi all'endpoint di verifica dei contenuti multimediali per evitare un codice di errore HTTP. Per altri tipi di eventi, aggiungi l'ID media all'URL media verification e invia una richiesta GET per monitorare la riproduzione.
  5. Rimuovi l'evento multimediale dalla coda.

endpoint API

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Parametri del percorso

MEDIA_VERIFICATION_URL Il valore restituito dall'endpoint di registrazione dello stream nel media_verification_url campo:
MEDIA_VERIFICATION_URL
AD_MEDIA_ID L'ID elemento multimediale dell'annuncio completo, come visualizzato nei metadati ID3 dello stream:
AD_MEDIA_ID

Valori di rendimento previsti

HTTP/1.1 204 No Content Risposta vuota riuscita.
HTTP/1.1 404 Not Found L'ID verifica dei contenuti multimediali non è stato riconosciuto.
HTTP/1.1 409 Conflict L'ID verifica dei contenuti multimediali è già stato inviato.

Richiesta di esempio (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Risposta di esempio

HTTP/1.1 204 No Content

Limitazioni

Se utilizzi l'API all'interno delle visualizzazioni web, si applicano le seguenti limitazioni per quanto riguarda il targeting:

  • UserAgent: il parametro user agent viene passato come valore specifico del browser anziché della piattaforma di base.
  • rdid, idtype, is_lat: l'ID dispositivo non viene passato correttamente, il che limita la funzionalità delle seguenti funzionalità:
    • Quota limite
    • Rotazione sequenziale degli annunci
    • Segmentazione e targeting per pubblico
Avanti
Panoramica