La vita di un annuncio

Introduzione

Questo documento illustra la vita di una trasmissione in diretta su YouTube, creata e gestita mediante l'API YouTube Live Streaming e l'API YouTube Content ID.

Risorse e tipi di risorse

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

Risorse dell'API Live Streaming di YouTube

Risorse dell'API YouTube Data

Risorse dell'API YouTube Content ID

Creare e gestire una trasmissione dal vivo

I passaggi seguenti spiegano come creare e gestire un evento dal vivo su YouTube. I passaggi sono suddivisi nelle seguenti fasi:

  1. Configurare l'annuncio
  2. Rivendicare i tuoi contenuti
  3. Prova
  4. Annuncio
  5. Concludere la trasmissione
  6. Creare un riferimento

Fase 1: configura la trasmissione

Passaggio 1.1: crea la tua trasmissione

Chiama il metodo liveBroadcasts.insert per aggiungere la tua trasmissione al programma di eventi dal vivo di YouTube. La risorsa liveBroadcast che stai inserendo deve definire dei valori per le proprietà elencate di seguito.

Tieni presente le seguenti linee guida durante la configurazione della trasmissione:

  • Se vuoi disporre di una fase di test per la tua trasmissione, quando puoi visualizzare la trasmissione video senza che anche gli 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 di entrambe le proprietà.

  • Se vuoi creare un riferimento dalla trasmissione registrata, devi impostare la relativa proprietà contentDetails.recordFromStart su true. Se vuoi rendere il video registrato disponibile per la riproduzione immediatamente dopo la fine della trasmissione, devi anche impostare la proprietà contentDetails.enableDvr su true. (Entrambe le proprietà hanno un valore predefinito pari a true).

  • Puoi aggiornare una delle proprietà contentDetails purché lo stato della trasmissione sia ancora created o ready.

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

  • Il titolo, la descrizione e lo stato della privacy della trasmissione e altri campi di metadati 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 API contiene la risorsa liveBroadcast che hai creato. Il tuo codice dovrebbe estrarre e archiviare id da quella risorsa. Avrai bisogno di questo valore per identificare la trasmissione nelle future richieste API. (puoi anche identificare la risorsa video che corrisponde alla risorsa liveBroadcast utilizzando lo stesso ID).

Passaggio 1: 2: crea il tuo 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 il video stream dell'evento. Quando crei il flusso, devi impostare i valori delle proprietà elencate di seguito:

Fatta eccezione per il titolo, non è possibile aggiornare questi valori dopo la creazione dello stream. Se devi modificarli, dovrai creare un flusso diverso ripetendo questo passaggio. Questo processo è discusso più in dettaglio nel passaggio 3.5 più avanti in questo documento.

Puoi anche impostare i valori per le seguenti proprietà:

  • snippet.description: come il titolo, 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 in modo efficace se un canale ha una relazione one-to-one o one-to-one tra liveBroadcast e liveStream:

    • Se utilizzi il valore predefinito della proprietà true, puoi usare 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 semplicemente 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 del flusso, la risposta API contiene la risorsa liveStream che hai creato. Il tuo codice dovrebbe estrarre e archiviare id da quella risorsa. Avrai bisogno di questo valore per identificare il flusso nelle richieste API future.

Passaggio 1:3: associa la trasmissione al relativo stream

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

Nel chiamare il metodo liveBroadcasts.bind, imposta il parametro id sull'ID trasmissione ottenuto nel passaggio 1.1 e il parametro streamId sull'ID streaming ottenuto nel passaggio 1.2.

Fase 2: rivendicazione dei contenuti

Se vuoi mostrare annunci durante la trasmissione, devi rivendicare il video trasmesso prima dell'inizio dell'evento. I passaggi seguenti spiegano questa procedura. Tieni presente che tutte le chiamate API discusse in questa fase sono definite nell'API di Content ID di YouTube.

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 l'asset.

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

Passaggio 2.2: definisci la proprietà della risorsa

I dati sulla proprietà di una risorsa identificano i suoi proprietari e i territori in cui ne sono proprietari. YouTube usa questi dati per determinare dove un proprietario può impostare le norme per un video rivendicato.

Ad esempio, se hai il diritto di trasmettere un evento negli Stati Uniti e un'altra emittente è proprietaria degli stessi diritti per il Canada, puoi definire norme diverse per il video trasmesso e per i video caricati dagli utenti che corrispondono al video trasmesso. La norma di corrispondenza sarà applicata ai video caricati dagli utenti corrispondenti negli Stati Uniti, mentre la norma dell'altro proprietario sarà 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 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 dal vivo.

Nota: devi impostare una norma di corrispondenza se hai intenzione 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, puoi ignorare questo passaggio.

Per impostare la norma di corrispondenza, devi prima identificare la norma da applicare. Puoi recuperare un elenco dei criteri esistenti chiamando il metodo policies.list oppure definire un nuovo criterio chiamando il metodo policies.insert. In ogni caso, devi acquisire il id della norma che vuoi applicare.

Una volta identificato il criterio, chiama il metodo assetMatchPolicy.update. In questa richiesta, imposta il parametro assetId sul valore id memorizzato nel passaggio 2.1.

Passaggio 2.4: rivendica il tuo video

In questo passaggio, crei una rivendicazione che collega il video che trasmetti alla risorsa che hai creato nel passaggio 2.1. La rivendicazione stabilisce una norma che si applica solo al video trasmesso. (I video caricati dagli utenti che corrispondono al tuo video trasmesso vengono regolati dalla norma di corrispondenza impostata nel passaggio precedente.)

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

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

Elaborazione della risposta dell'API

Quando inserisci la rivendicazione, la risposta API conterrà la risorsa claim che hai creato. Il tuo codice dovrebbe estrarre e archiviare id da quella risorsa. Utilizzerai il 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 eseguire annunci durante le interruzioni.

  • Se abiliti gli annunci preroll per la tua trasmissione, tutti gli spettatori visualizzeranno un annuncio quando iniziano a guardarlo, anche se si trovano nel mezzo.
  • Se abiliti gli annunci mid-roll per la tua trasmissione, potrai inserire i cue point degli annunci 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, incorpori un player che mostra lo stream monitor per la trasmissione, in modo da poter testare l'esperienza di visualizzazione. Si tratta di uno stream privato che ti consente di visualizzare l'anteprima del video trasmesso come apparirebbe agli spettatori di YouTube.

Tieni presente che puoi testare la trasmissione video solo se il relativo stream monitor è abilitato. Per impostazione predefinita, sono abilitati i flussi di monitoraggio delle trasmissioni. Puoi disattivare il flusso di monitoraggio di un annuncio impostando la proprietà contentDetails.monitorStream.enableMonitorStream su false durante la creazione o l'aggiornamento della trasmissione.

Passaggio 3.1: incorpora un player per monitorare lo stream

Recupera la tua 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 di YouTube che mostra lo stream monitorato.

Passaggio 3.2: avvia il video

Inizia a trasmettere video sul video stream.

Passaggio 3: 3: verifica che il video stream sia attivo

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

Passaggio 3.4: esegui la transizione dello stato della trasmissione ai 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, quindi 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 fino a un minuto. Durante questo periodo, dovresti eseguire il polling dell'API per controllare lo stato della trasmissione. Terminata la transizione, lo stato della trasmissione sarà testStarting. Una volta completata la transizione, lo stato sarà testing.

Passaggio 3.5: completa i test

Se il test ha avuto esito positivo, puoi andare alla fase 4. Tuttavia, in alcuni casi potrebbe essere necessario eseguire ulteriori test. Ad esempio, se il test rivela che il video stream non è configurato correttamente, devi correggerlo prima di procedere con la trasmissione.

Se il video stream non è configurato correttamente, devi annullare l'associazione (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 annullare l'associazione del video stream, chiama il metodo liveBroadcasts.bind nel 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 il video stream, 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 flusso alla trasmissione e i passaggi da 3.1 a 3.3 per testare il nuovo flusso.

Passaggio 3.6: attiva le proprietà autoStart e autoStop

Dopo aver completato correttamente 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 causerebbe effettivamente l'avvio della trasmissione.

Fase 4: trasmissione

In questa fase, il video trasmesso è visibile al pubblico.

Passaggio 4.1: avvia il video

Inizia a trasmettere video sul video stream.

Passaggio 4: 2: verifica che il video stream sia attivo

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

Passaggio 4.3: esegui la transizione dello stato della trasmissione in diretta

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, quindi 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, dovresti eseguire il polling dell'API per controllare lo stato della trasmissione. Terminata la transizione, lo stato della trasmissione sarà liveStarting. Lo stato sarà live al termine della transizione e gli spettatori potranno guardare la tua trasmissione da quel momento nello stream del monitor.

Tieni presente i seguenti effetti di questo comando:

  • Se hai abilitato lo stream di monitoraggio per la tua trasmissione (vedi il passaggio 3.1), potrai vedere lo stream di monitoraggio in un player incorporato.
  • Se hai impostato un valore per la proprietà contentDetails.streamDetails.broadcastStreamDelayMs della trasmissione, lo streaming trasmesso agli altri spettatori verrà ritardato.

Passaggio 4.4: inserisci le interruzioni pubblicitarie nella tua 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 dell'interruzione (in secondi) che vuoi mostrare. (il valore predefinito è 30).

Al 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 dell'annuncio. La riproduzione di un annuncio dipende da una serie di fattori, come la disponibilità dell'annuncio e la cronologia di visualizzazione dell'annuncio dello spettatore. Gli spettatori che hanno ricevuto un'interruzione pubblicitaria tornano alla trasmissione al termine dell'interruzione pubblicitaria, mentre gli spettatori a cui non viene mostrato un annuncio continuano a visualizzare lo stream trasmesso durante l'interruzione.

La Guida introduttiva fornisce ulteriori informazioni sull'esperienza di visualizzazione durante l'interruzione pubblicitaria di una trasmissione dal vivo.

Fase 5: termina la trasmissione

Passaggio 5.1: interrompi lo streaming

Questa operazione termina il tuo test del sistema di trasmissione dal vivo di YouTube.

Passaggio 5.2: transizione dello stato della trasmissione per il completamento

Quando vuoi 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, quindi imposta il valore del parametro broadcastStatus su complete.

Se hai impostato le proprietà contentDetails.recordFromStart e contentDetails.enableDvr della trasmissione su true, al termine dell'evento dal vivo il pubblico può guardare immediatamente la riproduzione dell'evento dal vivo.

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 i video caricati dagli utenti che corrispondono alla trasmissione e di gestirli in base alla norma di corrispondenza impostata nel passaggio 2.3.

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

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

Prima di poter creare un riferimento a partire da un video, YouTube deve terminare l'elaborazione di una trasmissione o di un video caricato. Per determinare se l'elaborazione del video è terminata, compila il metodo videos.list dell'API di dati di YouTube per impostare il parametro part su status e il parametro id sull'ID trasmissione che hai memorizzato nel passaggio 1.1.

La risposta dell'API alla 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 tuo 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.

Pubblicazione di Content ID dal vivo

Alcuni partner di YouTube sono in grado di creare un riferimento prima delle transizioni di trasmissione allo stato testing, ma questa funzionalità non è disponibile per tutti i partner. Durante questa fase, YouTube genera e aggiorna continuamente il riferimento dal tuo stream di trasmissione del tuo evento dal vivo durante la sua trasmissione in corso. Inoltre, YouTube cerca i video corrispondenti caricati dagli utenti mentre la trasmissione è ancora in corso. Tieni presente che, se crei un riferimento prima che inizi una trasmissione, viene attivata automaticamente la registrazione per la trasmissione e non è possibile disattivarla dopo la creazione del riferimento.

Per attivare la trasmissione dal vivo di Content ID, prova a eseguire le azioni descritte nel passaggio 6.2 dopo aver rivendicato il tuo video nel passaggio 2.4. Se il tuo account partner non ha ricevuto l'approvazione per creare un riferimento per una trasmissione dal vivo prima della trasmissione, l'API restituirà un errore fingerprintingNotAllowed. In tal caso, devi attendere il completamento della trasmissione, come descritto nei passaggi 6.1 e 6.2 precedenti, prima di creare il riferimento.