Migrar al receptor web

En esta guía, se explica cómo migrar una app de Cast Receiver v2 a la versión más reciente de la app.

El nuevo SDK de Cast Application Framework (CAF), también conocido como Web Receiver v3, es una actualización importante del SDK de la app receptora v2. El SDK de receptor web proporciona un SDK sencillo y optimizado para desarrollar aplicaciones multimedia de receptores web.

El receptor web proporciona una API que es más coherente con las nuevas API de emisoras de CAF. Proporciona una integración completa de un reproductor (MPL y Shaka) y plena implementación y compatibilidad con los comandos de voz de Cast multimedia y Asistente de Google. El SDK de CAF también proporciona una IU predeterminada a la que se puede aplicar diseño con facilidad mediante CSS y un servicio de vinculación de datos para simplificar la implementación de la IU.

¿Por qué migrar?

Cuando se migra una aplicación Receiver v2 a Web Receiver, una gran cantidad de código que se ocupa del reproductor se puede eliminar, de manera que puedas concentrarte en escribir la lógica empresarial específica de la aplicación.

CAF integra de forma continua los reproductores MPL y Shaka para admitir una variedad más amplia de tipos de contenido, como las transmisiones HTTP en vivo (TS y CMAF), MPEG-DASH, Smooth Streaming y los tipos compatibles con la propiedad fuente de elementos multimedia (MP3, MP4, Icecast, etcétera). Para obtener una lista completa, consulta Contenido multimedia compatible con Google Cast. Actualmente, CAF no es compatible con un reproductor proporcionado por el usuario.

Si migras a CAF, se agregará la compatibilidad con el control por voz con Asistente de Google. Todos los comandos por voz nuevos de Asistente de Google se admitirán automáticamente cuando se use CAF.

Además de ser compatible con nuevos comandos de contenido multimedia, como "cambiar pistas por idioma" y "cambiar la velocidad de reproducción", CAF también ofrece mejor cola, compatibilidad integrada con anuncios y mejor compatibilidad con transmisiones en vivo.

¿Qué cambió?

La API de Web Receiver intenta seguir las convenciones que ingresaron los remitentes de CAF para Android y iOS, y es bastante diferente de la versión 2.

El receptor web utiliza un espacio de nombres cast.framework nuevo en lugar del espacio de nombres cast.receiver para todas las API expuestas. Muchos de los objetos de datos que la v2 usó son los mismos en CAF y se exponen en el espacio de nombres cast.framework.messages (en la mayoría de los casos, en cast.receiver.media).

Los siguientes servicios de la v2 se reemplazan por los servicios de CAF correspondientes:

  • Se reemplazó la clase CastReceiverManager por CastReceiverContext, que es un singleton que administra la sesión de transmisión, los remitentes, el envío de mensajes personalizados y los eventos del sistema global. CastReceiverOptions se puede usar para proporcionar al contexto opciones de la aplicación global (como la cola, la versión del receptor, la configuración de reproducción, etc.).
  • Se reemplazó la clase MediaManager por PlayerManager, que es una propiedad del singleton CastReceiverContext, y administra la sesión multimedia, las solicitudes multimedia, las solicitudes de voz de Asistente de Google (CommandAndControlManager en la versión 2) y activa eventos multimedia. La configuración de los reproductores (cast.player.api.Host en MPL) es proporcionada por PlaybackConfig, que se puede proporcionar de manera global o por solicitud de carga.

El PlayerManager también expone las nuevas clases de subadministrador:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

// Set global options.
const options = new cast.framework.CastReceiverOptions();
options.versionCode = DEVELOPERS_APP_VERSION;

context.start(options);

Lógica empresarial del receptor

Los controladores de eventos expuestos de la versión 2 del receptor (como CastReceiverManager.onReady o MediaManager.onLoad) para agregar la lógica empresarial. En CAF, los controladores de eventos se reemplazan por los objetos de escucha de eventos (CastReceiverContext.addEventListener) y los interceptores de mensajes (PlayerManager.setMessageInterceptor). El receptor web puede tener varios objetos de escucha de eventos para un evento (el objeto de escucha no afecta el evento) y un interceptor por mensaje. El interceptor puede actualizar o controlar la solicitud (mostrar una solicitud modificada, un mensaje de éxito o un mensaje de error) y puede ser un controlador asíncrono que muestra una promesa.

El interceptor de solicitud de carga es el lugar más común para agregar la lógica específica de la aplicación. En el caso de las solicitudes de carga de un remitente, el interceptor de carga puede convertir el ID de contenido en una URL de contenido. También se llama al interceptor de carga para las solicitudes de precarga y almacenamiento en caché si no se proporcionó un interceptor explícito para la carga previa o la caché previa.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      // Resolve entity to content id
      if (request.media.entity && !request.media.contentId) {
        return getMediaByEntity(request.media.entity).then(
            media => {
              request.media.contentId = media.url;
              return request;
            });
      }
      return request;
    });

El controlador de estado de medios personalizado v2 también se reemplaza por un interceptor de mensajes para el mensaje de estado de medios. Las apps de receptores web que no quieren exponer la URL de medios en el estado multimedia pueden proporcionar un agente de resolución de URL (PlayerManager.setMediaUrlResolver), que proporciona la URL de medios para una solicitud de carga. CAF usa esa URL internamente y no se proporciona en el estado de medios.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.MEDIA_STATUS,
    status => {
      // Disable seek.
      status.supportedMediaCommands &=
          ~cast.framework.messages.Command.SEEK
      return status;
    });

Eventos

El receptor web proporciona un conjunto amplio de eventos de CastReceiverContext y PlayerManager. Las apps de receptores web pueden tener varios objetos de escucha en cualquier evento y también pueden proporcionar un objeto de escucha a varios eventos. (Consulta cast.framework.events.category para ver algunos grupos de eventos).

Los eventos cubren cualquier solicitud del usuario, el progreso de la reproducción, el procesamiento del reproductor y cualquier evento de elemento multimedia de bajo nivel (el CAF no expone el elemento multimedia en sí).

La app receptora web puede agregar objetos de escucha de eventos en función de los cuales actuar (por ejemplo, agregar definición de pistas de texto cuando se completa la carga) o estadísticas.

// Log all media commands
playerManager.addEventListener(
    cast.framework.events.category.REQUEST,
    event => logEvent(event.type));

Autobús de mensajes personalizado

El CAF no expone el bus de mensajes en la API, sino que proporciona CastReceiverContext.addCustomMessageListener a fin de agregar un objeto de escucha de mensajes para un espacio de nombres específico (solo uno por espacio de nombres) y CastReceiverContext.sendCustomMessage a fin de enviar un mensaje en un espacio de nombres. Todos los espacios de nombres deben declararse antes de iniciar el receptor web (es decir, antes de llamar a CastReceiverContext.start). Los espacios de nombres se pueden declarar agregando un objeto de escucha de mensajes o se pueden proporcionar como una opción de inicio en CastReceiverOptions.customNamespaces.

const options = new cast.framework.CastReceiverOptions();
options.customNamespaces = {
    CUSTOM_NS: cast.framework.system.MessageType.JSON
};
context.start(options);

context.sendCustomMessage(CUSTOM_NS, {
  type: 'status'
  message: 'Playing'
});

IU predeterminada

CAF proporciona una IU de receptor web predeterminada que muestra una barra de progreso de reproducción y metadatos multimedia según sea necesario. La IU predeterminada se proporciona como un elemento personalizado (<cast-media-player>) al que se le puede dar estilo con un estilo similar a la de CSS.

<style>
   cast-media-player { --splash-image: url("splash.png"); }
</style>
<cast-media-player></cast-media-player>

Para obtener más personalización, una app receptora web puede implementar su propia IU. El receptor web proporciona la clase cast.framework.ui.PlayerDataBinder para ayudar a vincular un objeto de IU al estado de reproducción del receptor web.