La vita di un annuncio

Introduzione

Questo documento illustra il ciclo di vita di una trasmissione live su YouTube creata e gestita utilizzando l'API YouTube Live Streaming e l'API YouTube Content ID.

Risorse e tipi di risorse

Come spiegato nella guida Guida introduttiva, una risorsa è una singola entità di dati con un identificatore univoco. Per creare e gestire le live su YouTube, utilizzerai diversi tipi di risorse definite nell'ambito dell'API YouTube Data o dell'API YouTube Content ID. Le risorse elencate nell'intestazione API YouTube Live Streaming sono tecnicamente definite in queste altre API, ma sono elencate separatamente perché vengono utilizzate solo per le trasmissioni live.

Risorse dell'API YouTube Live Streaming

Risorse dell'API YouTube Data

Risorse dell'API Content ID di YouTube

Crea e gestisci una trasmissione live

I passaggi riportati di seguito spiegano come creare e gestire un evento live su YouTube. I passaggi sono suddivisi nelle seguenti fasi:

  1. Configurare la trasmissione
  2. Rivendicare i tuoi contenuti
  3. Test
  4. Annuncio
  5. Concludi la trasmissione
  6. Crea un riferimento

Fase 1: configura la trasmissione

Passaggio 1.1: crea la trasmissione

Chiama il metodo liveBroadcasts.insert per aggiungere la tua trasmissione alla programmazione degli eventi live di YouTube. La risorsa liveBroadcast che stai inserendo deve definire i valori per le proprietà elencate di seguito.

Tieni presente le seguenti linee guida quando configuri la trasmissione:

  • Se vuoi avere una fase di test per la tua trasmissione, durante la quale puoi visualizzare la trasmissione video senza che altri spettatori possano vederla, devi impostare la proprietà contentDetails.monitorStream.enableMonitorStream su true e la proprietà contentDetails.enableAutoStart su false. Questi sono i valori predefiniti per entrambe le proprietà.

  • Se vuoi creare un riferimento dalla trasmissione registrata, devi impostare la proprietà contentDetails.recordFromStart della trasmissione su true. Se vuoi rendere disponibile il video registrato per la riproduzione immediatamente dopo il termine della trasmissione, devi anche impostare la proprietà contentDetails.enableDvr su true. Entrambe queste proprietà hanno un valore predefinito di true.

  • Se vuoi limitare le regioni in cui è visualizzabile la trasmissione, puoi impostare la proprietà contentDetails.availabilityConfig. Questa proprietà ti consente di bloccare regioni specifiche o di limitare la disponibilità a un elenco definito di regioni. Puoi anche specificare finestre temporali per la disponibilità regionale.

  • Puoi specificare facoltativamente la categoria del video per la trasmissione utilizzando la proprietà snippet.categoryId. Se non specificata, la categoria predefinita è Entertainment.

  • Puoi aggiornare qualsiasi proprietà di contentDetails, purché lo stato della trasmissione sia ancora created o ready.

  • Puoi aggiornare l'ora di inizio e l'ora di fine programmate della trasmissione, purché lo stato della trasmissione sia created, ready o testing.

  • Il titolo, la descrizione, la categoria, lo stato della privacy e altri campi di metadati della trasmissione che fanno parte della risorsa video della trasmissione possono essere aggiornati in qualsiasi momento.

    Nota: se vuoi che il tuo video sia disponibile solo per utenti di YouTube specifici, imposta il valore della proprietà status.privacyStatus su unlisted o private in base alle tue esigenze.

Elaborazione della risposta dell'API

Quando chiami il metodo liveBroadcasts.insert, la risposta dell'API contiene la risorsa liveBroadcast che hai creato. Il codice deve estrarre e archiviare id dalla risorsa. Avrai bisogno di questo valore per identificare la trasmissione nelle richieste API future. (Puoi anche identificare la risorsa video che corrisponde alla risorsa liveBroadcast utilizzando lo stesso ID.)

Passaggio 1.2: crea lo stream

Una risorsa liveStream ti consente di trasmettere il tuo video su YouTube e descrive i contenuti che stai trasmettendo. Ogni trasmissione deve essere associata esattamente a uno stream.

Chiama il metodo liveStreams.insert per creare lo stream video per il tuo evento. Quando crei lo stream, devi impostare i valori per le proprietà elencate di seguito:

Ad eccezione del titolo dello stream, questi valori non possono essere aggiornati dopo la creazione dello stream. Se devi modificarli, devi creare un flusso diverso ripetendo questo passaggio. Questo processo viene descritto in modo più dettagliato nel passaggio 3.5 più avanti in questo documento.

Hai anche la possibilità di impostare i valori per le seguenti proprietà:

  • snippet.description: come il titolo dello stream, la descrizione dello stream può essere aggiornata dopo la creazione dello stream. Né il titolo né la descrizione sono visibili agli utenti di YouTube.

  • [contentDetails.isReusable](

    /youtube/data/live/reference/rest/v3/liveStreams#contentDetails.isReusable)

    Indica se lo stream è riutilizzabile, ovvero se può essere associato a più trasmissioni. Il valore di questa proprietà determina se un canale ha una relazione many-to-one o one-to-one tra le risorse liveBroadcast e liveStream:

    • Se utilizzi il valore predefinito della proprietà true, puoi utilizzare la stessa risorsa liveStream per tutte le trasmissioni di un canale. Ciò significa che non è necessario ripetere questo passaggio (1.2) per ogni trasmissione. Puoi invece riutilizzare l'ID stream per le trasmissioni successive.
    • Se imposti il valore della proprietà su false, devi creare un nuovo stream per ogni trasmissione.

Dopo aver inviato la richiesta API per il flusso, la risposta dell'API contiene la risorsa liveStream che hai creato. Il tuo codice deve estrarre e archiviare il valore id da questa risorsa. Ti servirà questo valore per identificare lo stream nelle richieste API future.

Passaggio 1.3: associa la trasmissione allo stream

Dopo aver creato le risorse liveBroadcast e liveStream, devi associarle utilizzando il metodo liveBroadcasts.bind. Questa azione collega i bit video che trasmetterai a YouTube alla trasmissione dell'evento per quel video.

Quando chiami il metodo liveBroadcasts.bind, imposta il parametro id sull'ID trasmissione ottenuto nel passaggio 1.1 e il parametro streamId sull'ID stream ottenuto nel passaggio 1.2.

Fase 2: rivendica i tuoi contenuti

Se vuoi mostrare annunci durante la trasmissione, devi rivendicare il video della trasmissione prima dell'inizio dell'evento. Segui questi passaggi per configurare la trasmissione, il video e gli annunci. Tieni presente che il canale del proprietario della trasmissione deve essere idoneo alla pubblicazione di annunci.

Tieni presente che tutte le chiamate API descritte in questa fase sono definite nell'API YouTube Content ID.

Passaggio 2.1: crea un asset

Una risorsa asset rappresenta una proprietà intellettuale. In questo caso, l'asset è la tua trasmissione. Chiama il metodo assets.insert per creare la risorsa.

La risposta dell'API conterrà la risorsa asset che hai creato. Il codice deve estrarre e memorizzare id dalla risorsa, in quanto avrai bisogno di questo valore per identificare l'asset nelle future richieste API.

Passaggio 2.2: definisci la proprietà dell'asset

I dati sulla proprietà di una risorsa identificano i proprietari di una risorsa e i territori in cui la possiedono. YouTube utilizza questi dati per determinare dove un proprietario può impostare la norma per un video rivendicato.

Ad esempio, se hai il diritto di trasmettere un evento negli Stati Uniti e un altro emittente possiede gli stessi diritti per il Canada, potete definire norme diverse per il video della trasmissione e per i video caricati dagli utenti che corrispondono al video della trasmissione. La tua norma di corrispondenza verrà applicata ai video caricati dagli utenti corrispondenti negli Stati Uniti, mentre la norma dell'altro proprietario verrà applicata ai video corrispondenti in Canada.

Per definire i territori di proprietà dell'asset, chiama il metodo ownership.update. In questa richiesta, imposta il parametro assetId sul valore id memorizzato nel passaggio 2.1.

Passaggio 2.3: imposta la norma di corrispondenza della risorsa

Le norme di corrispondenza di una risorsa spiegano cosa deve fare YouTube quando un utente carica un video che corrisponde a un riferimento associato alla risorsa. In questo caso, la norma di corrispondenza indicherà in che modo YouTube deve gestire un video caricato che corrisponde alla tua trasmissione live.

Nota: devi impostare una norma di corrispondenza se prevedi di creare un riferimento dal tuo video trasmesso e di utilizzarlo per identificare i video caricati dagli utenti che corrispondono alla tua trasmissione. In caso contrario, ignora questo passaggio.

Per impostare la norma di corrispondenza, devi prima identificare la norma che vuoi applicare. Puoi recuperare un elenco di policy esistenti chiamando il metodo policies.list oppure puoi definire una nuova policy chiamando il metodo policies.insert. In entrambi i casi, devi acquisire id della policy che vuoi applicare.

Una volta identificata la policy, chiama il metodo assetMatchPolicy.update. In questa richiesta, imposta il parametro assetId sul valore id che hai memorizzato nel passaggio 2.1.

Passaggio 2.4: rivendica il video

In questo passaggio, crei una rivendicazione che collega il video che trasmetterai alla risorsa che hai creato nel passaggio 2.1. La rivendicazione imposta una norma che si applica solo al video della trasmissione. I video caricati dagli utenti che corrispondono al tuo video della trasmissione sono coperti dalla norma di corrispondenza impostata nel passaggio precedente.

Per creare una rivendicazione, chiama il metodo claims.insert. Nella risorsa claim che inserisci, devi impostare i valori per le seguenti proprietà:

  • assetId: hai ottenuto questo valore nel passaggio 2.1.
  • videoId: l'ID trasmissione che hai ottenuto nel passaggio 1.1.
  • policy: questa è una risorsa policy. Puoi applicare una policy esistente impostando la proprietà id della risorsa sull'ID della policy esistente. Il passaggio precedente spiega come recuperare l'ID di una norma esistente.
  • contentType: imposta questo valore su audiovisual.

Elaborazione della risposta dell'API

Quando inserisci la rivendicazione, la risposta dell'API conterrà la risorsa claim che hai creato. Il codice deve estrarre e archiviare il id da questa risorsa. Utilizzerai questo valore in un secondo momento per creare un riferimento dal video elaborato.

Passaggio 2.5: aggiorna le impostazioni dell'annuncio per la trasmissione

Devi impostare le opzioni pubblicitarie per il tuo video se vuoi pubblicare un annuncio pre-roll quando gli spettatori iniziano a guardare la tua trasmissione o pubblicare annunci durante le interruzioni della trasmissione.

  • Se attivi gli annunci pre-roll per la tua trasmissione, tutti gli spettatori vedranno un annuncio quando iniziano a guardare la trasmissione, anche se iniziano a guardarla a metà.
  • Se attivi gli annunci mid-roll per la tua trasmissione, potrai inserire cue point pubblicitari durante la trasmissione.

Per attivare gli annunci, chiama il metodo videoAdvertisingOptions.update. Nella richiesta, imposta il parametro videoId sulla trasmissione id che hai ottenuto nel passaggio 1.1. Utilizza la proprietà adFormats[] della risorsa videoAdvertisingOption per identificare i formati dell'annuncio (preroll, midroll o postroll) che vuoi attivare.

Fase 3: test

Durante questa fase, incorpora un player che mostra lo stream di monitoraggio della tua trasmissione in modo da poter testare l'esperienza di visualizzazione. Lo stream di monitoraggio è uno stream privato che ti consente di visualizzare l'anteprima del video trasmesso così come apparirebbe agli spettatori di YouTube.

Tieni presente che puoi testare la trasmissione video solo se lo stream di monitoraggio è attivo. Per impostazione predefinita, i flussi di monitoraggio delle trasmissioni sono attivi. Puoi disattivare lo stream di monitoraggio di una trasmissione impostando la proprietà contentDetails.monitorStream.enableMonitorStream su false quando crei o aggiorni la trasmissione.

Passaggio 3.1: incorpora un player di streaming del monitor

Recupera la trasmissione utilizzando il metodo liveBroadcasts.list ed estrai il valore della proprietà contentDetails.streamDetails.monitorStreamEmbedHtml. Questo valore contiene il codice HTML necessario per incorporare un player YouTube che mostri lo stream del monitor.

Passaggio 3.2: avvia il video

Inizia a trasmettere video sul tuo stream video.

Passaggio 3.3: verifica che lo stream video sia attivo

Chiama il metodo liveStreams.list per recuperare la risorsa liveStream associata alla tua trasmissione. Verifica che il valore della proprietà status.streamStatus sia active, il che indica che i server di YouTube ricevono correttamente i dati dal tuo encoder.

Passaggio 3.4: imposta lo stato della trasmissione su "testing"

Chiama il metodo liveBroadcasts.transition per aggiornare lo stato della trasmissione. Imposta il valore parametro id sull'ID trasmissione ottenuto nel passaggio 1.1 e imposta il valore parametro broadcastStatus su testing.

Dopo aver chiamato il metodo liveBroadcasts.transition, il completamento della transizione potrebbe richiedere diversi secondi o anche un minuto. Durante questo periodo di tempo, devi eseguire il polling dell'API per controllare lo stato della trasmissione. Fino al completamento della transizione, lo stato della trasmissione sarà testStarting. Lo stato sarà testing al termine della transizione.

Passaggio 3.5: completa i test

Se il test è andato a buon fine, puoi passare alla fase 4. Tuttavia, in alcuni casi, potrebbe essere necessario eseguire ulteriori test. Ad esempio, se i test rivelano che lo stream video non è configurato correttamente, devi risolvere il problema prima di procedere con la trasmissione.

Se lo stream video non è configurato correttamente, devi scollegare (ed eliminare) lo stream esistente e crearne uno nuovo. Ad esempio, uno stream potrebbe non essere configurato correttamente se specifica il formato video sbagliato.

  1. Per dissociare lo stream video, chiama il metodo liveBroadcasts.bind del passaggio 1.3. Nella richiesta API, imposta il parametro id sul valore id ottenuto nel passaggio 1.1. Non includere il parametro streamId nella richiesta.

  2. Per eliminare lo stream video, chiama il metodo liveStreams.delete. Nella richiesta, imposta il parametro id sul valore id ottenuto nel passaggio 1.2.

  3. Ripeti il passaggio 1.2 per creare una nuova risorsa liveStream configurata correttamente. Quindi ripeti il passaggio 1.3 per associare il nuovo stream alla trasmissione e i passaggi da 3.1 a 3.3 per testare il nuovo stream.

Passaggio 3.6: attiva le proprietà autoStart e autoStop

Dopo aver completato la fase di test, puoi impostare le proprietà contentDetails.enableAutoStart e contentDetails.enableAutoStop della trasmissione su true prima dell'inizio della trasmissione effettiva. Queste proprietà non possono essere impostate su true prima della fase di test, perché il test avvierebbe effettivamente la trasmissione.

Fase 4: trasmissione

Durante questa fase, il video della trasmissione è visibile al pubblico.

Passaggio 4.1: avvia il video

Inizia a trasmettere video sul tuo stream video.

Passaggio 4.2: verifica che lo stream video sia attivo

Chiama il metodo liveStreams.list per recuperare la risorsa liveStream associata alla tua trasmissione. Verifica che il valore della proprietà status.streamStatus sia active, il che indica che i server di YouTube ricevono correttamente i dati dal tuo encoder.

Passaggio 4.3: imposta lo stato della trasmissione su live

Importante: questo passaggio rende il video visibile al tuo pubblico.

Chiama il metodo liveBroadcasts.transition per aggiornare lo stato della trasmissione. Imposta il valore del parametro id sull'ID trasmissione ottenuto nel passaggio 1.1 e imposta il valore del parametro broadcastStatus su live.

Se imposti la proprietà contentDetails.enableAutoStart della risorsa liveBroadcast su true, non è necessario chiamare il metodo liveBroadcasts.transition.

Dopo aver effettuato questa chiamata API o, se hai impostato la proprietà contentDetails.enableAutoStart su true, dopo aver avviato lo streaming, in genere devi attendere da 5 a 10 secondi per il completamento della transizione. La transizione potrebbe richiedere fino a un minuto. Durante questo periodo, devi eseguire il polling dell'API per controllare lo stato della trasmissione. Fino al completamento della transizione, lo stato della trasmissione sarà liveStarting. Lo stato diventerà live una volta completata la transizione e gli spettatori potranno guardare la trasmissione da quel punto nello stream di monitoraggio.

Tieni presente i seguenti effetti di questo comando:

  • Se hai attivato lo stream di monitoraggio per la trasmissione (vedi il passaggio 3.1), potrai visualizzarlo in un player incorporato.
  • Se avevi impostato un valore per la proprietà contentDetails.streamDetails.broadcastStreamDelayMs della trasmissione, lo stream della trasmissione, visibile agli altri spettatori, verrà ritardato di quel periodo di tempo.

Passaggio 4.4: inserisci interruzioni pubblicitarie nella trasmissione

Chiama il metodo liveBroadcasts.cuepoint per inserire un cue point. Il cue point potrebbe attivare un'interruzione pubblicitaria. Nella risorsa cuepoint fornita nel corpo della richiesta, imposta la proprietà durationSecs sulla durata desiderata della pausa (in secondi) che vuoi mostrare. (Il valore predefinito è 30.)

In questo momento, YouTube tenta di riprodurre un annuncio nel video player per tutti gli spettatori che stavano guardando la trasmissione quando è stato inserito il cue point pubblicitario. La riproduzione di un annuncio dipende da una serie di fattori, come la disponibilità degli annunci e la cronologia delle visualizzazioni degli annunci dello spettatore. Gli spettatori che visualizzano un'interruzione pubblicitaria tornano alla trasmissione al termine dell'interruzione, mentre gli spettatori a cui non viene mostrato un annuncio continuano a guardare lo stream della trasmissione durante l'interruzione.

La guida Inizia fornisce ulteriori informazioni sull'esperienza di visualizzazione durante un'interruzione pubblicitaria di una trasmissione live.

Fase 5: concludi la trasmissione

Passaggio 5.1: interrompi lo streaming

Questo conclude il test del sistema di trasmissione live di YouTube.

Passaggio 5.2: imposta lo stato della trasmissione su Completato

Quando è tutto pronto per interrompere la trasmissione, chiama il metodo liveBroadcasts.transition dell'API per aggiornare lo stato della trasmissione. Imposta il valore del parametro id sull'ID trasmissione ottenuto nel passaggio 1.1 e imposta il valore del parametro broadcastStatus su complete.

Se avevi impostato le proprietà contentDetails.recordFromStart e contentDetails.enableDvr della trasmissione su true, al termine dell'evento live il tuo pubblico potrà guardare immediatamente la riproduzione dell'evento live.

Fase 6: crea un riferimento

Una volta completata la registrazione dal vivo, puoi creare un riferimento dal video registrato. Questa azione indica a YouTube di cercare video caricati dagli utenti che corrispondono alla trasmissione e di gestirli in base alle norme di corrispondenza che hai impostato nel passaggio 2.3.

Importante: per creare il riferimento, devi aver impostato la proprietà contentDetails.recordFromStart della trasmissione su true.

Passaggio 6.1: esegui il polling dell'API di dati per lo stato del video

YouTube deve completare l'elaborazione di una trasmissione o di un video caricato prima che tu possa creare un riferimento da quel video. Per determinare se l'elaborazione del video è terminata, esegui il polling del metodo videos.list dell'API YouTube Data, impostando il parametro part su status e il parametro id sull'ID trasmissione memorizzato nel passaggio 1.1.

La risposta dell'API alla tua richiesta di polling conterrà una risorsa video. Quando il valore della proprietà status.uploadStatus della risorsa è processed, vai al passaggio 6.2.

Passaggio 6.2: crea un riferimento dal video elaborato

Per creare il riferimento, chiama il metodo references.insert dell'API Content ID e imposta il parametro claimId sull'ID rivendicazione memorizzato nel passaggio 2.4.

Invio di Content ID per i contenuti live

Alcuni partner di YouTube possono creare un riferimento prima che la trasmissione passi allo stato testing, ma questa funzionalità non è disponibile per tutti i partner. In questo flusso, YouTube genera e aggiorna continuamente il riferimento dallo stream di trasmissione dell'evento dal vivo mentre la trasmissione è in corso. Inoltre, YouTube cerca video corrispondenti caricati dagli utenti mentre la trasmissione è ancora in corso. Tieni presente che la creazione di un riferimento prima dell'inizio di una trasmissione attiva automaticamente la registrazione per la trasmissione e la registrazione non può essere disattivata dopo la creazione del riferimento.

Per attivare la trasmissione per la distribuzione live di Content ID, prova a eseguire le azioni descritte nel passaggio 6.2 dopo aver rivendicato il video nel passaggio 2.4. Se il tuo account partner non è stato approvato per la creazione di un riferimento per una trasmissione live prima che questa venga avviata, l'API restituirà un errore fingerprintingNotAllowed. In questo caso, devi attendere il completamento della trasmissione, come descritto nei passaggi 6.1 e 6.2 sopra, prima di creare il riferimento.