La vita di un annuncio

Introduzione

Questo documento descrive 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 eventi live su YouTube, utilizzerai diversi tipi di risorse definiti nell'API YouTube Data o nell'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

Creare e gestire una trasmissione dal vivo

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. Concludere la trasmissione
  6. Creare un riferimento

Fase 1: configura la trasmissione

Passaggio 1.1: crea la trasmissione

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

Quando configuri la trasmissione, tieni presente le seguenti linee guida:

  • 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 che il video registrato sia disponibile per la riproduzione immediatamente dopo la fine della trasmissione, devi impostare anche la proprietà contentDetails.enableDvr su true. Entrambe queste proprietà hanno un valore predefinito di true.

  • Puoi aggiornare una qualsiasi delle proprietà contentDetails finché lo stato della trasmissione è created o ready.

  • Puoi aggiornare l'ora di inizio e di fine pianificata della trasmissione finché lo stato della trasmissione è created, ready o testing.

  • Il titolo, la descrizione, 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 YouTube specifici, imposta il valore della proprietà status.privacyStatus su unlisted o private, a seconda delle 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 memorizzare il 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 a YouTube e descrive i contenuti che stai trasmettendo. Ogni trasmissione deve essere associata a un solo stream.

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

A 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. Questa procedura è descritta 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 - Indica se lo stream è riutilizzabile, il che significa che può essere associato a più trasmissioni. Il valore di questa proprietà determina effettivamente 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. In alternativa, puoi 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 lo stream, la risposta API contiene la risorsa liveStream che hai creato. Il codice deve estrarre e memorizzare id dalla risorsa. Avrai bisogno di questo valore per identificare lo stream nelle richieste API future.

Passaggio 1.3: collega la trasmissione al relativo stream

Dopo aver creato le risorse liveBroadcast e liveStream, devi associarle utilizzando il metodo liveBroadcasts.bind. Questa azione collega i bit del video che trasmetterai a YouTube con la 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. I passaggi seguenti spiegano questa procedura. Tieni presente che tutte le chiamate API descritte in questa fase sono definite nell'API Content ID di YouTube.

Passaggio 2.1: crea una risorsa

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

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

Passaggio 2.2: definisci la proprietà dell'asset

I dati di proprietà di una risorsa identificano i proprietari di una risorsa e i territori in cui possiedono la risorsa. 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à della risorsa, chiama il metodo ownership.update. In questa richiesta, imposta il parametro assetId sul valore id che hai memorizzato nel passaggio 2.1.

Passaggio 2.3: imposta la norma di corrispondenza della risorsa

La norma di corrispondenza di una risorsa spiega 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à come YouTube deve gestire un video caricato che corrisponde alla tua trasmissione live.

Nota:devi impostare una norma di corrispondenza se intendi creare un riferimento dal tuo video della trasmissione e 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 l'id della norma che vuoi applicare.

Una volta identificato il criterio, chiama il metodo assetMatchPolicy.update. In questa richiesta, imposta il parametro assetId sul 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 creata nel passaggio 2.1. La rivendicazione imposta norme che si applicano solo al tuo 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 richiesta, 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 ottenuto nel passaggio 1.1.
  • policy: si tratta di 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 policy 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 memorizzare id dalla 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 preroll quando gli spettatori iniziano a guardare la tua trasmissione o pubblicare annunci durante le interruzioni della trasmissione.

  • Se attivi gli annunci preroll 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 degli annunci (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. Il monitor stream è uno stream privato che ti consente di visualizzare l'anteprima del video della trasmissione così come apparirà agli spettatori di YouTube.

Tieni presente che puoi testare la trasmissione del video solo se lo stream di monitoraggio è attivato. 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 codificatore.

Passaggio 3.4: imposta lo stato della trasmissione su Test

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 testing.

Dopo aver chiamato il metodo liveBroadcasts.transition, il completamento della transizione potrebbe richiedere diversi secondi o anche un minuto. Durante questo periodo, devi eseguire il polling dell'API per controllare lo stato della trasmissione. Finché la transizione non sarà completata, 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 annullare il collegamento (ed eliminare) lo stream esistente e crearne uno nuovo. Ad esempio, uno stream potrebbe non essere configurato correttamente se specifica il formato video errato.

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

Una volta completata la fase di test, puoi impostare le proprietà contentDetails.enableAutoStart e contentDetails.enableAutoStop della trasmissione su true prima dell'inizio della trasmissione vera e propria. Queste proprietà non possono essere impostate su true prima della fase di test perché il test causerebbe l'avvio della trasmissione.

Fase 4: trasmetti

Durante questa fase, il video della trasmissione è visibile al tuo 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 codificatore.

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 devi 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 5-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 sarà live al termine della transizione e gli spettatori potranno guardare la trasmissione da quel punto del flusso del monitor.

Tieni presente i seguenti effetti di questo comando:

  • Se hai attivato il flusso di monitoraggio per la tua trasmissione, vedi il passaggio 3.1, potrai visualizzare il flusso di monitoraggio 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 questo 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à dell'annuncio e la cronologia di visualizzazione degli annunci dello spettatore. Gli spettatori che visualizzano una pausa pubblicitaria tornano alla trasmissione al termine della pausa, mentre gli spettatori che non visualizzano un annuncio continuano a guardare lo stream della trasmissione durante la pausa.

La guida Inizia fornisce maggiori informazioni sull'esperienza di visualizzazione durante la pausa pubblicitaria di una trasmissione live.

Fase 5: concludi la trasmissione

Passaggio 5.1: interrompi lo streaming

Il test del sistema di trasmissione live di YouTube è terminato.

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 Data per lo stato del video

YouTube deve terminare 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 che hai 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 di quella risorsa è processed, procedi al passaggio 6.2.

Passaggio 6.2: crea un riferimento a partire dal video elaborato

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

Invio di Content ID per i contenuti live

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

Per abilitare la trasmissione per la pubblicazione di Content ID in tempo reale, 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 si verifichi, 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.