Pausas publicitarias

Descripción general

El SDK de receptor web ofrece compatibilidad nativa con pausas publicitarias y anuncios complementarios. dentro de un flujo de medios determinado. Proporciona APIs para configurar la posición del anuncio, la fuente y el comportamiento de las pausas publicitarias y los clips de pausa asociados. En esta guía, se incluye Break se refiere a un intervalo de reproducción que contiene uno o más anuncios o anuncios bumper a cada anuncio o bumper publicitario BreakClip Estas pausas se asocian al contenido multimedia que se carga o reproduce.

Tipos de anuncios

El SDK del receptor web es compatible con la inserción de anuncios del cliente (CSAI) y el servidor. la inserción de anuncios unidos (SSAI). Los anuncios unidos por el cliente se pueden configurar manualmente mediante o extraída de los archivos de plantilla de VAST y VMAP. Los anuncios unidos por el servidor deben especificarse manualmente antes de que se cargue el contenido como anuncios incorporados o dinámicamente durante la reproducción de contenido como incorporado expandido. anuncios. Las implementaciones para cada uno de estos tipos de anuncios se describen en detalle a continuación.

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

Tipos de línea de tiempo del jugador

Cuando se crea una instancia de reproductor, el SDK del receptor web selecciona un tipo de línea de tiempo para admitir la reproducción de anuncios durante la reproducción de contenido, Cada línea de tiempo habilita determinados anuncios los tipos de salto de línea que se deben agregar. El tipo de línea de tiempo está determinado por el tipos de anuncios presentes durante el tiempo de carga en la MediaInformation de los LoadRequestData. Si hay pausas publicitarias incorporadas, se seleccionará el cronograma embedded. Si Si hay pausas publicitarias unidas por el cliente, se seleccionó el cronograma stitched. En caso de que no haya anuncios, el SDK usa embedded de forma predeterminada. en el cronograma. Una vez que se selecciona el cronograma, no se puede cambiar para el cronograma actual elemento multimedia. La siguiente tabla incluye una descripción detallada de cada cronograma.

Las figuras 1 a 3 que aparecen a continuación muestran algunos tipos de contenido con distintos tipos de anuncios y sus respectivos valores de cronograma. El contenido se configura con una pausa para anuncios previos al video. que contenga dos clips de pausa, y las pausas para anuncios durante el video y al final del video que contengan un clip de una sola pausa. El tiempo de reloj desde el inicio de la reproducción de contenido El tiempo multimedia del contenido principal y el momento de la pausa actual reproducción del clip de pausa están alineados debajo de cada figura.

Posicionamiento de la pausa

El SDK del receptor web permite que los desarrolladores especifiquen dónde deben estar las pausas publicitarias estableciendo position propiedad de Break. Este valor corresponde al tiempo multimedia del contenido principal. y se puede usar para crear pausas publicitarias pre-roll, mid-roll y post-roll. Se definen de la siguiente manera:

Matriz de interoperabilidad

Como punto de referencia rápido, en la Tabla 1, se muestra una descripción general de los tipos de anuncios y su compatibilidad con las funciones relacionadas con los anuncios.

Eventos

Cuando se produzcan eventos de ruptura de clave, el SDK de transmisión enviará eventos de tipo BreaksEvent Una app receptora puede suscribirse a ellos mediante PlayerManager. addEventListener en la API de Cloud.

Estos eventos se pueden usar para las estadísticas y el seguimiento de reproducción de anuncios. Cuando se usa VMAP (lista de reproducción de varios anuncios de video) y los anuncios VAST (plantilla de publicación de anuncios de video) se se usan, todos los eventos de seguimiento estándar proporcionados en las respuestas se que envía el SDK.

Los tipos de eventos se enumeran en la Tabla 2, junto con una descripción detallada del cuando se activan.

Inserción de anuncios

El SDK de transmisión permite que las aplicaciones inserten y quiten anuncios en diferentes momentos. de una sesión de transmisión. Los dos tipos de inserción de anuncios son estática y dinámica. La inserción de anuncios estáticos requiere que los anuncios se especifiquen en LoadRequestData antes de la creación del jugador. La inserción de anuncios dinámicos utiliza el BreakManager addBreak API para insertar saltos en el contenido ya cargado. Cada tipo de inserción es compatible con ciertos tipos de anuncios. Una compatibilidad se proporciona en la matriz de interoperabilidad.

Inserción de anuncios estáticos

La inserción de anuncios estáticos se caracteriza por agregar los metadatos relevantes del anuncio antes a la creación del jugador. Esta información se proporciona en el MediaInformation de la LoadRequestData. Por ejemplo, esto se puede establecer en la dirección solicitud de carga original, o la aplicación del receptor web la puede insertar interceptación de la solicitud LOAD. Una vez que se devuelve LoadRequestData al SDK de receptor web para el procesamiento, se crea el reproductor. Ver más en cargar medios. La muestra a continuación, se muestra un anuncio unido por el cliente manualmente que se agrega en la solicitud LOAD un interceptor.

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

Inserción de anuncios dinámicos

La inserción de anuncios dinámicos se caracteriza por configurar una pausa publicitaria durante el contenido reproducción. Para ello, se obtiene una instancia de BreakManager y se llama el addBreak en la API de Cloud. Esto requiere, como mínimo, dos parámetros, un incorporado expandido Break y un array de BreakClip. Se incluye una tercera propiedad opcional para forzar el envío de los cambios a Remitentes conectados a través de una transmisión MediaStatus cuando se establece en true. Cuándo agregar pausas y clips de pausa, los IDs correspondientes deben ser únicos. Estos anuncios solo se puede agregar una vez que se crea el reproductor. Se activa el SDK del receptor web. el PLAYER_LOADING una vez creado el reproductor. Consulta el siguiente ejemplo que muestra el uso en un controlador de eventos que responde a los cambios en los metadatos de ID3 de una transmisión y Crea objetos Break y BreakClip para insertarlo en el cronograma.

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

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

Eliminación de anuncio dinámico

Para eliminar las pausas dinámicas, la aplicación debe llamar removeBreakById durante la reproducción. La función toma un identificador de cadena de la pausa que se del cronograma. El breakId especificado debe apuntar a un elemento incorporado. pausa publicitaria. Si se detecta cualquier otro tipo de pausa publicitaria, esta seguirán estando en el cronograma. Consulta el siguiente ejemplo para quitar un receso.

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

breakManager.removeBreakById('break_midroll_embedded_expanded');

Comportamiento de las pausas

El SDK define un comportamiento predeterminado para cuando el jugador entra y sale de las pausas. y ofrece una manera de personalizarlo aún más con algunas de las APIs proporcionadas en BreakManager

Comportamiento de interrupción predeterminado

Cuando se ingresa un Break a través de la reproducción normal o buscando más de un Break, el SDK evaluará si el usuario ya lo vio o no verificando el isWatched propiedad. Cuando se crea, el valor predeterminado de una pausa para esta propiedad es false. Si la propiedad es true, el descanso no se jugará cuando se ingrese y se encuentre principal seguirá reproduciéndose. Si la propiedad es false, la pausa se realizará se reproducen al ingresarlos.

Cuando buscas pausas pasadas, la implementación predeterminada obtiene todos los Break. elementos cuyo position se encuentra entre el rango de la operación de búsqueda seekFrom y seekTo de salida. De esta lista de pausas, el SDK reproducirá la Break cuyo position es el valor más cercano al valor seekTo y cuya propiedad isWatched está configurada en false La propiedad isWatched de esa pausa se establecerá en true. el jugador comenzará a reproducir sus clips de pausa. Una vez que se mira el descanso, el contenido principal reanudará la reproducción desde la posición seekTo. Si no existe no se reproducirá ningún descanso y se reanudará el contenido principal se reproducirá en la posición seekTo.

Durante la pausa en la reproducción, el SDK transmitirá todas las actualizaciones relevantes a las remitentes de la MediaStatus Estas aplicaciones usarán las transmisiones para actualizar su IU para anuncios leyendo el breakStatus propiedad. Esta propiedad se define solo durante la pausa de la reproducción.

Las aplicaciones receptoras también pueden consultar directamente información relacionada con la posición del cabezal de reproducción con respecto a la hora actual de BreakClip se muestra llamando a PlayerManager getBreakClipCurrentTimeSec Del mismo modo, las aplicaciones pueden consultar la duración de la BreakClip actual mediante llamando getBreakClipDurationSec

Comportamiento de pausa personalizado

El comportamiento predeterminado para las pausas y los clips de pausa se pueden modificar con el setBreakClipLoadInterceptor y setBreakSeekInterceptor métodos proporcionados en BreakManager.

Interceptor de salto de salto

El interceptor de búsqueda de pausa permite que la app controle el comportamiento de la búsqueda a las pausas publicitarias. La función se activa cuando se solicita una operación de búsqueda. que adelanta o retrocede en uno o más cortes. Cuando se los llama, BreakSeekData se pasa como parámetro a la función de devolución de llamada. El objeto BreakSeekData contiene un array de Break objetos cuya propiedad position está establecida en un número entre el valor actual tiempo de cabeza de reproducción definido como seekFrom y la hora de destino de la búsqueda seekTo.

Este interceptor permite que se puedan usar los objetos Break en las pausas correspondientes. modificados. Cuando se implementa, el interceptor de búsqueda de pausa debe especificar qué anuncio pausas para reproducir mostrando un objeto BreakSeekData modificado opcionalmente. El el jugador reproducirá todas las pausas incluidas en el valor que se muestra. Si un valor de null o no se muestra nada del interceptor de búsqueda de pausa, la pausa se se omitió.

Consulta la siguiente muestra para ver una implementación simple del interceptor que anula el comportamiento predeterminado para mirar todas las pausas publicitarias que se buscan con el excepción de las pausas ya vistas.

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

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

Interceptor de carga de clips de interrupción

Cuando se usa el interceptor de carga de clip de pausa, se puede modificar un objeto BreakClip. antes de que comience la reproducción.

El interceptor de carga del clip de pausa solo se llama para pausas unidas en la línea de tiempo y se pueden configurar usando setBreakClipLoadInterceptor Antes de ingresar un Break, se llama a este interceptor una vez por cada individuo. Se definió BreakClip en esa pausa. El SDK pasa la versión original BreakClip como parámetro de la función de devolución de llamada. Luego, la aplicación puede modificar este BreakClip y lo mostrará para que el SDK pueda recuperar y mostrar la pausa clip con la configuración actualizada. Si se muestra null o no se muestra nada, la pausa se omite el clip.

A continuación, puedes ver un ejemplo que modifica el contentUrl de los clips de pausa con una función de utilidad llama a getUrlFromClipId, en la que el id de BreakClip se asigna a una URL.

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

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

Omisión de anuncio

El SDK de receptor web proporciona APIs para omitir pausas publicitarias y clips de pausa individuales. en una pausa publicitaria. El SDK también les permite a los usuarios omitir clips de pausa interactuar con sus aplicaciones emisoras o dispositivos de pantalla inteligente.

Clips de pausa que los usuarios pueden omitir

Si configuras clips de pausa como que se pueden omitir, los usuarios podrán interactuar con los remitentes conectados aplicaciones y dispositivos de visualización inteligente para omitir de forma opcional el resto de un se está reproduciendo el clip de pausa. Configurar el whenSkippable a una cantidad de segundos no negativa, se habilitará esta función para el BreakClip. El reproductor considerará que se puede omitir el clip de pausa una vez que clip de pausa se reprodujo durante ese número de segundos. Establecer este valor en 0 permite que los usuarios omitan el clip de pausa inmediatamente.

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

Esta información se puede configurar en la solicitud de carga original del remitente o en app receptora. Cuando se omite, un clip de pausa en una pausa publicitaria de la línea de tiempo unida dejará de reproducir el clip de pausa actual. El reproductor cargará los siguientes romper el clip si está presente o cargar el contenido principal. Cuando se omite, un clip de pausa en una La pausa publicitaria en la línea de tiempo incorporada buscará hasta el final del clip de la pausa. continuar con la reproducción de la transmisión en ese momento.

Cómo omitir anuncios de forma programática

Los anuncios también se pueden omitir automáticamente sin ninguna interacción del usuario.

Para evitar una interrupción completa de la reproducción, una aplicación debe establecer la isWatched propiedad de un elemento Break en true. Esto puede hacerse en cualquier momento durante o la reproducción de contenido. La propiedad isWatched se evalúa según cuando se alcanza el position de un descanso en el tiempo actual del contenido principal. En en ese punto, el jugador determinará si se debe ingresar o no un descanso. Consulta la siguiente muestra, en la que se repiten todas las pausas y se modifica la cuando se esté cargando el reproductor.

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

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

Para omitir un clip de pausa específico de forma programática, Se debe usar el interceptor de carga de clip de ruptura. De muestra null o no muestra un valor en la función de devolución de llamada, el clip se omitirá ese descanso.

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

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});