Aggiungi funzionalità avanzate all'app Web Sender

Interruzioni pubblicitarie

L'SDK Web Sender supporta le interruzioni pubblicitarie e gli annunci companion all'interno di un determinato stream multimediale.

Per scoprire di più sul funzionamento delle interruzioni pubblicitarie, consulta la Panoramica delle interruzioni pubblicitarie per i ricevitori web.

Sebbene le interruzioni possano essere specificate sia sul mittente che sul ricevente, è consigliabile specificarle sul Ricevitore web e sul Ricevitore Android TV per mantenere un comportamento coerente sulle varie piattaforme.

Sul web, specifica le interruzioni pubblicitarie in un comando di caricamento utilizzando BreakClip e Break:

let breakClip1 = new BreakClip('bc0');
breakClip1.title = 'Clip title'
breakClip1.posterUrl = 'https://www.some.url';
breakClip1.duration = 60;
breakClip.whenSKippable = 5;

let breakClip2 = ...
let breakClip3 = ...

let break1 = new Break('b0', ['bc0', 'bc1', 'bc2'], 10);

let mediaInfo = new chrome.cast.media.MediaInfo(<contentId>, '<contentType');
...
mediaInfo.breakClips = [breakClip1, breakClip2, breakClip3];
mediaInfo.breaks = [break1];

let request = new chrome.cast.media.LoadRequest(mediaInfo);

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request)

Utilizzo delle API di canali

Una traccia può essere un oggetto di testo (sottotitoli o sottotitoli codificati) o un oggetto stream audio o video. Le API Tracks ti consentono di utilizzare questi oggetti nella tua applicazione.

Nota: i ricevitori Con stile e Media predefiniti ti consentono di utilizzare solo le tracce di testo con l'API. Per lavorare con le tracce audio e video, devi sviluppare un ricevitore personalizzato.

Un oggetto Track rappresenta un canale nell'SDK. Puoi configurare un canale e assegnargli un ID univoco come segue:

var englishSubtitle = new chrome.cast.media.Track(1, // track ID
  chrome.cast.media.TrackType.TEXT);
englishSubtitle.trackContentId = 'https://some-url/caption_en.vtt';
englishSubtitle.trackContentType = 'text/vtt';
englishSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
englishSubtitle.name = 'English Subtitles';
englishSubtitle.language = 'en-US';
englishSubtitle.customData = null;

var frenchSubtitle = new chrome.cast.media.Track(2, // track ID
  chrome.cast.media.TrackType.TEXT);
frenchSubtitle.trackContentId = 'https://some-url/caption_fr.vtt';
frenchSubtitle.trackContentType = 'text/vtt';
frenchSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
frenchSubtitle.name = 'French Subtitles';
frenchSubtitle.language = 'fr';
frenchSubtitle.customData = null;

var frenchAudio = new chrome.cast.media.Track(3, // track ID
  chrome.cast.media.TrackType.AUDIO);
frenchAudio.trackContentId = 'trk0001';
frenchAudio.trackContentType = 'audio/mp3';
frenchAudio.subtype = null;
frenchAudio.name = 'French Audio';
frenchAudio.language = 'fr';
frenchAudio.customData = null;

Un elemento multimediale può avere più tracce; ad esempio, può avere più sottotitoli (ognuno per una lingua diversa) o più stream audio alternativi (per lingue diverse).

MediaInfo è la classe che modella un elemento multimediale. Per associare una raccolta di oggetti Track a un elemento multimediale, aggiorna la relativa proprietà tracks. Questa associazione deve essere effettuata prima che i contenuti multimediali vengano caricati sul ricevitore:

var tracks = [englishSubtitle, frenchSubtitle, frenchAudio];
var mediaInfo = new chrome.cast.media.MediaInfo(mediaURL);
mediaInfo.contentType = 'video/mp4';
mediaInfo.metadata = new chrome.cast.media.GenericMediaMetadata();
mediaInfo.customData = null;
mediaInfo.streamType = chrome.cast.media.StreamType.BUFFERED;
mediaInfo.textTrackStyle = new chrome.cast.media.TextTrackStyle();
mediaInfo.duration = null;
mediaInfo.tracks = tracks;

Puoi impostare i canali attivi nella richiesta media activeTrackIds.

Puoi anche attivare uno o più canali associati all'elemento media dopo il caricamento dei contenuti multimediali chiamando EditTracksInfoRequest(opt_activeTrackIds, opt_textTrackStyle) e passando gli ID dei canali da attivare in opt_activeTrackIds. Tieni presente che entrambi i parametri sono facoltativi e puoi scegliere quali canali o stili attivi impostare a tua discrezione. Ad esempio, ecco come attivare i sottotitoli in francese (2) e l'audio in francese (3):

var activeTrackIds = [2, 3];
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(activeTrackIds);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

Per rimuovere tutte le tracce audio o video dai contenuti multimediali correnti, imposta semplicemente mediaInfo.tracks=null (un array vuoto) e ricarica i contenuti multimediali.

Per rimuovere tutte le tracce di testo dai contenuti multimediali correnti (ad esempio disattivando i sottotitoli), esegui una delle seguenti operazioni:

• Aggiorna var activeTrackIds = [2, 3]; (mostrato in precedenza) in modo che includa solo [3], la traccia audio.
• Imposta mediaInfo.tracks=null. Tieni presente che non è necessario ricaricare i contenuti multimediali per disattivare i sottotitoli codificati (track.hidden). L'invio di un array activeTracksId che non contiene un trackId attivato in precedenza disattiva la traccia di testo.

Applicazione di stili alle tracce di testo

TextTrackStyle è l'oggetto che racchiude le informazioni sugli stili di una traccia di testo. Dopo aver creato o aggiornato un oggetto TextTrackStyle esistente, puoi applicarlo all'elemento multimediale in riproduzione chiamando il relativo metodo editTrackInfo, ad esempio:

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(textTrackStyle);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

Puoi monitorare lo stato della richiesta con il risultato dei richiami, positivo o con errore, e aggiornare di conseguenza il mittente originale.

Le applicazioni devono consentire agli utenti di aggiornare lo stile delle tracce di testo utilizzando le impostazioni fornite dal sistema o dall'applicazione stessa.

Puoi applicare stili ai seguenti elementi di stile della traccia di testo:

• Colore e opacità del primo piano (testo)
• Colore dello sfondo e opacità
• Tipo di bordo
• Colore bordo
• Scala dei caratteri
• Famiglia di caratteri
• Stile carattere

Ad esempio, imposta il colore del testo su rosso con opacità del 75% come segue:

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
textTrackStyle.foregroundColor = '#80FF0000';

Controllo del volume

Puoi utilizzare i tasti RemotePlayer e RemotePlayerController per regolare il volume del ricevitore.

function changeVolume(newVolume) {
  player.volumeLevel = newVolume;
  playerController.setVolumeLevel();
  // Update sender UI to reflect change
}

L'app mittente deve rispettare le seguenti linee guida per il controllo del volume:

• L'applicazione del mittente deve sincronizzarsi con il ricevente in modo che l'UI del mittente registri sempre il volume in base al ricevente. Utilizza il callback RemotePlayerEventType.VOLUME_LEVEL_CHANGED e RemotePlayerEventType.IS_MUTED_CHANGED per mantenere il volume sul mittente. Per ulteriori informazioni, consulta Aggiornamenti sullo stato.
• Le app mittente non devono impostare il livello del volume su un livello specifico predefinito o impostare il livello del volume sul volume della suoneria/dei contenuti multimediali del dispositivo mittente quando l'app viene caricata sul ricevente.

Consulta Controlli del volume del mittente nell'elenco di controllo per la progettazione.

Invio di messaggi multimediali al destinatario

Media Messages può essere inviato dal mittente al destinatario. Ad esempio, per inviare un messaggio SKIP_AD al destinatario:

// Get a handle to the skip button element
const skipButton = document.getElementById('skip');
skipButton.addEventListener("click", function() {
  if (castSession) {
    const media = castSession.getMediaSession();
    castSession.sendMessage('urn:x-cast:com.google.cast.media', {
      type: 'SKIP_AD',
      requestId: 1,
      mediaSessionId: media.mediaSessionId
    });
  }
});

Aggiornamenti di stato

Quando più mittenti sono collegati allo stesso destinatario, è importante che ciascun mittente sia a conoscenza delle modifiche apportate al destinatario, anche se queste sono state avviate da altri mittenti.

Nota: questo è importante per tutte le app, non solo per quelle che supportano esplicitamente più mittenti, perché alcuni dispositivi di trasmissione hanno input di controllo (telecomandi, pulsanti) che si comportano come mittenti virtuali e influiscono sullo stato del ricevitore.

A tal fine, la tua applicazione deve registrare tutti gli ascoltatori necessari su RemotePlayerController. Se il valore TextTrackStyle del media corrente cambia, tutti i mittenti collegati riceveranno una notifica e le proprietà corrispondenti della sessione media corrente, ad esempio activeTrackIds e textTrackStyle del campo MediaInfo, verranno inviate ai mittenti nei callback. In questo caso, l'SDK del ricevitore non verifica se il nuovo stile è diverso da quello precedente e invia una notifica a tutti i mittenti collegati, indipendentemente da ciò.

Nota: l'elenco dei canali associati ai contenuti multimediali attualmente caricati non può essere modificato. Se necessario, devi aggiornare le informazioni sui canali nell'oggetto MediaInfo e ricaricare i contenuti multimediali.

Indicatore avanzamento

La visualizzazione della posizione di riproduzione con un indicatore di avanzamento sul mittente è un requisito per la maggior parte delle app. Le API Cast utilizzano il protocollo multimediale Cast, che ottimizza il consumo di larghezza di banda per questo e altri scenari, quindi non è necessario implementare la sincronizzazione dello stato. Per l'implementazione corretta di un indicatore di avanzamento per la riproduzione di contenuti multimediali utilizzando le API, consulta l'app di esempio CastVideos-chrome.

Requisiti CORS

Per lo streaming multimediale adattivo, Google Cast richiede la presenza di intestazioni CORS, ma anche semplici stream multimediali mp4 richiedono CORS se includono tracce. Se vuoi attivare i canali per qualsiasi contenuto multimediale, devi attivare CORS sia per gli stream dei canali sia per gli stream multimediali. Pertanto, se non hai intestazioni CORS disponibili per i tuoi semplici contenuti multimediali mp4 sul server e aggiungi una semplice traccia di sottotitoli codificati, non potrai riprodurre in streaming i contenuti multimediali a meno che non aggiorni il server in modo da includere le intestazioni CORS appropriate.

Sono necessarie le seguenti intestazioni: Content-Type, Accept-Encoding e Range. Tieni presente che le ultime due intestazioni, Accept-Encoding e Range, sono intestazioni aggiuntive che potresti non aver avuto bisogno in precedenza.

I caratteri jolly "*" non possono essere utilizzati per l'intestazione Access-Control-Allow-Origin. Se la pagina contiene contenuti multimediali protetti, deve utilizzare un dominio anziché un carattere jolly.

Riprendere una sessione senza ricaricare la pagina web

Per riprendere un CastSession esistente, utilizza requestSessionById(sessionId) con il sessionId della sessione a cui stai tentando di partecipare.

Il sessionId si trova nel CastSession attivo utilizzando getSessionId() dopo aver chiamato loadMedia().

L'approccio consigliato è:

1. Chiama loadMedia() per avviare la sessione
2. Memorizza sessionId localmente
3. Rientra nella sessione utilizzando requestSessionById(sessionId) se necessario

let sessionId;

function rejoinCastSession() {
  chrome.cast.requestSessionById(sessionId);

  // Add any business logic to load new content or only resume the session
}

document.getElementById('play-button').addEventListener(("click"), function() {
  if (sessionId == null) {
    let castSession = cast.framework.CastContext.getInstance().getCurrentSession();
    if (castSession) {
      let mediaInfo = createMediaInfo();
      let request = new chrome.cast.media.LoadRequest(mediaInfo);
      castSession.loadMedia(request)

      sessionId = CastSession.getSessionId();
    } else {
      console.log("Error: Attempting to play media without a Cast Session");
    }
  } else {
    rejoinCastSession();
  }
});

Passaggi successivi

Ecco le funzionalità che puoi aggiungere all'app mittente web. Ora puoi creare un'app mittente per un'altra piattaforma (Android o iOS) o creare un'app di ricezione.