Utilizza un'integrazione personalizzata

Prima di iniziare

Questo documento descrive solo le istruzioni di riproduzione, in assenza dei SDK IMA DAI.

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

Nota: consigliamo vivamente di utilizzare l'SDK IMA DAI sulle piattaforme in cui è supportato.

Se l'SDK IMA non è disponibile per la piattaforma prevista, hai bisogno del tuo per chiamare le API richieste e attivare le verifiche degli elementi multimediali degli annunci per trovare le regole.

A questo scopo, avrai bisogno delle seguenti informazioni:

Località	La Regione Google Cloud dove è stata creata la configurazione live: LOCATION
Numero progetto	Il numero del progetto Google Cloud che utilizza lo strumento di stitching video API: PROJECT_NUMBER
Token OAuth	Token OAuth di breve durata di un account di servizio con l'utente dello stitching video ruolo: OAUTH_TOKEN Scopri di più su la creazione di token OAuth di breve durata. Punto chiave: Il token OAuth può essere riutilizzato in più richieste purché non sia scaduto.
Codice di rete	Il codice di rete Ad Manager per richiedere annunci: NETWORK_CODE
ID configurazione VOD	L'ID configurazione VOD specificato durante la creazione dell'evento di streaming 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 facoltativo di codifica json parametri di targeting.

JSON risposta

media_verification_url	L'URL di base per inviare un ping agli eventi di monitoraggio della riproduzione. Una verifica dei contenuti multimediali completa L'URL viene creato aggiungendo un ID evento dell'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 in cui scade la sessione di streaming corrente, indicata come ISO 8601 stringa data/ora in yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm formato.

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"
  }
}

Esempio di risposta

{
  "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 archivia i valori pertinenti.

Suggerimento: gli URL forniti nella risposta dell'API sono soggetti a modifica senza notifica. Pertanto, utilizza gli URL forniti nella risposta dell'API anziché a costruirli autonomamente. Questo aiuta a garantire che il codice continui a funzionare correttamente quando cambiano gli URL.

Genera una sessione VOD dello stitching video Cloud

Effettua una richiesta POST all'endpoint di registrazione della sessione VOD. In cambio, Ricevere una risposta JSON contenente l'URI del manifest dello stream e i metadati relative a interruzioni pubblicitarie, annunci ed eventi pubblicitari.

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 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 di progetto. location e l'ID configurazione VOD con il valore seguente formato: projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
adTracking	Imposta "CLIENT" per attivare il monitoraggio lato client.
gamSettings	Un oggetto contenente il codice di rete e stream id 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 nella richiesta del testo.
vodConfig	La stessa stringa vodConfig inviata all'API nella richiesta del testo.
gamSettings	Lo stesso oggetto gamSettings inviato all'API nella tua richiesta del testo.

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"
  }
}

Esempio di risposta

{
  "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

Effettua una richiesta GET al metadata_url che hai ricevuto al momento della registrazione il tuo stream con Ad Manager. Questo passaggio deve essere eseguito dopo aver ricevuto il manifest unito dall'URI di riproduzione.

Riceverai a sua volta un oggetto JSON che descrive le interruzioni pubblicitarie, gli annunci e l'annuncio dello stream eventi.

Endpoint API

GET: METADATA_URL
Host: dai.google.com

JSON risposta

tags	Una serie di coppie chiave/valore che descrivono gli eventi multimediali degli annunci che si verificano. all'interno dello stream. Ogni chiave è composta dai primi 17 caratteri un ID elemento multimediale annuncio che verrà visualizzato nei metadati ID3 dello stream o, nel caso di eventi "progress", l'intero ID multimediale dell'annuncio. Ogni valore corrisponde a un con le seguenti proprietà: ad: l'ID dell'annuncio contenente l'evento multimediale dell'annuncio. ad_break_id: l'ID dell'interruzione pubblicitaria contenente l'annuncio un evento multimediale. type: il tipo di evento multimediale dell'annuncio. I valori possono essere uno dei seguenti: start - L'annuncio è iniziato firstquartile: l'annuncio è completo al 25%. midpoint: l'annuncio è completo al 50%. thirdquartile: l'annuncio è completo al 75%. complete: l'annuncio è terminato. progress: attivato ogni secondo durante la riproduzione di un annuncio.
ads	Una serie di coppie chiave/valore che descrivono gli annunci che verranno visualizzati all'interno flusso di dati. Ogni chiave è un ID annuncio. Ogni valore è un oggetto con le seguenti caratteristiche proprietà: ad_break_id: l'ID dell'interruzione pubblicitaria contenente l'annuncio un evento multimediale. position: la posizione dell'annuncio all'interno dell'interruzione pubblicitaria. tieni presente che il primo annuncio di una pausa ha la posizione 1. duration: la durata dell'annuncio in secondi con virgola mobile. title: il titolo dell'annuncio, come definito nel modello VAST. description: la descrizione dell'annuncio, come definita nella il modello VAST. ad_system: il sistema di annunci, come definito in VAST. ad_system: l'ID annuncio, come definito nel file VAST. ad_system: l'ID creatività, come definito nel file VAST. clickthrough_url: l'URL da aprire quando un utente interagisce con l'annuncio. universal_ad_id: un oggetto che rappresenta l'universale come definito in VAST.
ad_breaks	Una serie di coppie chiave-valore che descrivono le interruzioni pubblicitarie che si verificheranno. all'interno dello stream. Ogni chiave è un ID interruzione pubblicitaria. Ogni valore corrisponde a un con le seguenti proprietà: type: il tipo di interruzione pubblicitaria. I valori saranno 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'annuncio un'interruzione in secondi con rappresentazione 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. Ad ogni aggiornamento dal player o con una frequenza impostata (500 ms l'opzione consigliata), controlla la coda degli eventi multimediali per verificare se sono presenti eventi riprodotti di recente confrontando i timestamp degli eventi con la testina di riproduzione.
3. Per gli eventi multimediali che confermi di aver riprodotto, controlla il tipo cercando l'ID elemento multimediale 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 media 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 di verifica dei media completo per un evento dell'annuncio, aggiungi l'ID evento dell'annuncio completo al valore media_verification_url dal risposta di creazione dello stream.
4. Utilizzare "avanzamento" per tenere traccia della presenza di un utente durante 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 multimediale dell'annuncio completo, così come appare nei metadati ID3 dello stream: AD_MEDIA_ID

Valori restituiti 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

Esempio di risposta

HTTP/1.1 204 No Content

Limitazioni

Se utilizzi l'API all'interno di WebView, si applicano le seguenti limitazioni in relazione a al targeting:

• UserAgent: il parametro user agent viene trasmesso come valore specifico del browser. anziché dalla piattaforma sottostante.
• rdid, idtype, is_lat: l'ID dispositivo non viene trasmesso correttamente. limita la funzionalità delle seguenti caratteristiche:
  • Quota limite
  • Rotazione sequenziale degli annunci
  • Segmentazione e targeting del pubblico