Aggiungi funzionalità avanzate all'app Web Sender

Interruzioni pubblicitarie

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

Consulta la panoramica sulle interruzioni pubblicitarie su ricevitore web per saperne di più su come funzionano le interruzioni pubblicitarie.

Sebbene le interruzioni possano essere specificate sia sul mittente che sul destinatario, è consigliabile specificarle sul web ricevitore e sul ricevitore Android TV per mantenere un comportamento coerente su tutte le 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 monitoraggio

Una traccia può essere un oggetto di testo (sottotitoli o sottotitoli) oppure un oggetto stream audio o video. Le API Tracce consentono di lavorare con questi oggetti nell'applicazione.

Un oggetto Track rappresenta una traccia nell'SDK. Puoi configurare una traccia e assegnarle 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 (ciascuno 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, devi aggiornare la relativa proprietà tracks. Questa associazione deve essere effettuata prima che l'elemento multimediale venga caricato sul destinatario:

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 le tracce attive nella richiesta activeTrackIds di contenuti multimediali.

Puoi anche attivare una o più tracce associate all'elemento multimediale, dopo il caricamento dei contenuti multimediali, chiamando EditTracksInfoRequest(opt_activeTrackIds, opt_textTrackStyle) e trasmettendo gli ID delle tracce da attivare in opt_activeTrackIds. Tieni presente che entrambi i parametri sono facoltativi e puoi scegliere quali tracce 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 dal contenuto multimediale corrente, imposta mediaInfo.tracks=null (un array vuoto) e ricarica il contenuto multimediale.

Per rimuovere tutte le tracce di testo dal supporto corrente (ad esempio disattivando i sottotitoli), procedi in uno dei seguenti modi:

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

Stile delle 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 attualmente in riproduzione chiamando il relativo metodo editTrackInfo, in questo modo:

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 callback (riuscita o con un errore) e aggiornare il mittente di origine di conseguenza.

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

Puoi applicare uno stile ai seguenti elementi di stile delle tracce di testo:

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

Ad esempio, imposta il colore del testo su rosso con un'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 impostare il volume del ricevitore.

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

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

  • L'applicazione del mittente deve sincronizzarsi con il destinatario in modo che la UI del mittente registri sempre il volume in base al destinatario. Usa il callback RemotePlayerEventType.VOLUME_LEVEL_CHANGED e RemotePlayerEventType.IS_MUTED_CHANGED per mantenere il volume del mittente. Per ulteriori informazioni, consulta la sezione Aggiornamenti dello stato.
  • Le app mittente non devono impostare il livello del volume a un livello specifico predefinito né impostare il livello del volume sul volume della suoneria o dei contenuti multimediali del dispositivo mittente quando l'app viene caricata sul ricevitore.

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

Invio di messaggi multimediali al destinatario

Media Messages possono essere inviati 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 sullo stato

Quando più mittenti sono connessi allo stesso destinatario, è importante che ciascun mittente sia a conoscenza delle modifiche sul destinatario anche se tali modifiche sono state avviate da altri mittenti.

A questo scopo, la tua applicazione deve registrare tutti i listener necessari sul RemotePlayerController. Se il TextTrackStyle dei contenuti multimediali correnti cambia, tutti i mittenti connessi riceveranno una notifica e le proprietà corrispondenti della sessione multimediale corrente, come activeTrackIds e textTrackStyle del campo MediaInfo verranno inviate ai mittenti nei callback. In questo caso, l'SDK del destinatario non verifica se il nuovo stile è diverso da quello precedente e invia una notifica a tutti i mittenti connessi.

Indicatore avanzamento

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

Requisiti CORS

Per lo streaming multimediale adattivo, Google Cast richiede la presenza di intestazioni CORS, ma anche gli stream multimediali mp4 semplici richiedono la tecnologia CORS se includono Track. Se desideri abilitare le tracce per qualsiasi supporto multimediale, devi abilitare CORS sia per i flussi di tracce che per quelli multimediali. Pertanto, se sul server non sono disponibili intestazioni CORS per i contenuti mp4 semplici e poi aggiungi una semplice traccia di sottotitoli, non potrai trasmettere in streaming i tuoi contenuti multimediali a meno che non aggiorni il server in modo da includere le intestazioni CORS appropriate.

Devi avere 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 bisogno in precedenza.

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

Ripresa di 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 accedere.

Puoi trovare sessionId sul CastSession attivo tramite getSessionId() dopo aver chiamato loadMedia().

L'approccio consigliato è:

  1. Chiama il numero loadMedia() per avviare la sessione
  2. Archivia sessionId localmente
  3. Accedi di nuovo alla 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

Con questo si concluderanno le funzionalità che puoi aggiungere alla tua app Web Sender. Ora puoi creare un'app mittente per un'altra piattaforma (Android o iOS) oppure creare un'app di ricezione.