Mostrar anuncios en contenido de vídeo

2024-07-05

Advertencia

A partir del 1 de junio de 2020, se cerrará la plataforma de monetización de anuncios de Microsoft para aplicaciones para UWP de Windows. Más información

En este tutorial se muestra cómo usar la clase AdScheduler para mostrar anuncios en contenido de vídeo en una aplicación de Plataforma universal de Windows (UWP) escrita con JavaScript con HTML.

Nota:

Esta característica solo se admite actualmente para aplicaciones para UWP escritas con JavaScript con HTML.

AdScheduler funciona con medios de streaming y progresivos, y usa formatos de carga de VMAP (VAST) 2.0/3.0 y VMAP estándar de IAB. Mediante el uso de estándares, AdScheduler es independiente del servicio de anuncios con el que interactúa.

La publicidad para el contenido de vídeo difiere en función de si el programa está por debajo de diez minutos (formato corto) o más de diez minutos (formulario largo). Aunque este último es más complicado de configurar en el servicio, realmente no hay ninguna diferencia en cómo escribe el código del lado cliente. Si el AdScheduler recibe una carga VAST con un solo anuncio en lugar de un manifiesto, se trata como si el manifiesto llamara para un anuncio pre-roll (un salto a la vez 00:00).

Requisitos previos

Instale el SDK de Microsoft Advertising con Visual Studio 2015 o una versión posterior.
El proyecto debe usar el control MediaPlayer para proporcionar el contenido de vídeo en el que se programarán los anuncios. Este control está disponible en la colección TVHelpers de bibliotecas disponibles en Microsoft en GitHub.

En el ejemplo siguiente se muestra cómo declarar un objeto MediaPlayer en marcado HTML. Normalmente, este marcado pertenece a la <body> sección del archivo index.html (u otro archivo HTML según corresponda para el proyecto).
```
<div id="MediaPlayerDiv" data-win-control="TVJS.MediaPlayer">
  <video src="URL to your content">
  </video>
</div>
```
En el ejemplo siguiente se muestra cómo establecer un objeto MediaPlayer en código JavaScript.
```
var mediaPlayerDiv = document.createElement("div");
document.body.appendChild(mediaPlayerDiv);

var videoElement = document.createElement("video");
videoElement.src = "<URL to your content>";
mediaPlayerDiv.appendChild(videoElement);

var mediaPlayer = new TVJS.MediaPlayer(mediaPlayerDiv);
```

Cómo usar la clase AdScheduler en el código

En Visual Studio, abra el proyecto o cree un proyecto.
Si el proyecto tiene como destino Cualquier CPU, actualice el proyecto para usar una salida de compilación específica de la arquitectura (por ejemplo, x86). Si el proyecto tiene como destino Cualquier CPU, no podrá agregar correctamente una referencia a la biblioteca de Microsoft Advertising en los pasos siguientes. Para obtener más información, consulte Errores de referencia causados por cualquier CPU en el proyecto.
Agregue una referencia a la biblioteca SDK de Microsoft Advertising para JavaScript al proyecto.
1. En la ventana Explorador de soluciones, haga clic con el botón derecho en Referencias y seleccione Agregar referencia...
2. En el Administrador de referencias, expanda Universal Windows, haga clic en Extensiones y, a continuación, active la casilla situada junto a SDK de Microsoft Advertising para JavaScript (versión 10.0).
3. En el Administrador de referencias, haga clic en Aceptar.
Agregue el archivo AdScheduler.js al proyecto:
1. En Visual Studio, haga clic en Proyecto y administrar paquetes NuGet.
2. En el cuadro de búsqueda, escriba Microsoft.StoreServices.VideoAdScheduler e instale el paquete Microsoft.StoreServices.VideoAdScheduler. El archivo AdScheduler.js se agrega al archivo .. Subdirectorio /js en el proyecto.
Abra el archivo index.html (u otro archivo HTML según corresponda para el proyecto). En la <head> sección , después de las referencias de JavaScript del proyecto de default.css y main.js, agregue la referencia a ad.js y adscheduler.js.
```
<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
<script src="/js/adscheduler.js"></script>
```
Nota:

Esta línea debe colocarse en la <head> sección después de incluir main.js; de lo contrario, se producirá un error al compilar el proyecto.
En el archivo main.js del proyecto, agregue código que cree un nuevo objeto AdScheduler . Pase el objeto MediaPlayer que hospeda el contenido del vídeo. El código debe colocarse para que se ejecute después de WinJS.UI.processAll.
```
var myMediaPlayer = document.getElementById("MediaPlayerDiv");
var myAdScheduler = new MicrosoftNSJS.Advertising.AdScheduler(myMediaPlayer);
```
Use los métodos requestSchedule o requestScheduleByUrl del objeto AdScheduler para solicitar una programación de anuncios desde el servidor e insertarlo en la escala de tiempo de MediaPlayer y, a continuación, reproducir el medio de vídeo.
- Si es un asociado de Microsoft que ha recibido permiso para solicitar una programación de anuncios desde el servidor de anuncios de Microsoft, use requestSchedule y especifique el identificador de aplicación y el identificador de unidad de anuncio proporcionados por su representante de Microsoft.
  
  Este método adopta la forma de una promesa, que es una construcción asincrónica en la que se pasan dos punteros de función: un puntero para que la función onComplete llame cuando la promesa se complete correctamente y un puntero para que la función onError llame si se encuentra un error. En la función onComplete, inicie la reproducción del contenido de vídeo. El anuncio comenzará a jugar a la hora programada. En la función onError , controle el error y, a continuación, inicie la reproducción del vídeo. El contenido del vídeo se reproducirá sin un anuncio. El argumento de la función onError es un objeto que contiene los siguientes miembros.
```
myAdScheduler.requestSchedule("your application ID", "your ad unit ID").then(
  function promiseSuccessHandler(schedule) {
      // Success: play the video content with the scheduled ads.
      myMediaPlayer.tvControl.play();
  },
  function promiseErrorHandler(err) {
      // Error: play the video content without the ads.
      myMediaPlayer.tvControl.play();
  });
```
- Para solicitar una programación de anuncios desde un servidor de anuncios que no es de Microsoft, use requestScheduleByUrl y pase el URI del servidor. Este método también adopta la forma de una promesa que acepta punteros para las funciones onComplete y onError . La carga de anuncios que se devuelve del servidor debe cumplir los formatos de carga de plantilla de servicio de anuncios de vídeo (VAST) o Video Multiple Ad Playlist (VMAP).
```
myAdScheduler.requestScheduleByUrl("your URL").then(
  function promiseSuccessHandler(schedule) {
      // Success: play the video content with the scheduled ads.
      myMediaPlayer.winControl.play();
  },
  function promiseErrorHandler(evt) {
      // Error: play the video content without the ads.
      myMediaPlayer.winControl.play();
  });
```
Nota:

Debes esperar a que requestSchedule o requestScheduleByUrl vuelva antes de empezar a reproducir el contenido de vídeo principal en MediaPlayer. A partir de reproducir elementos multimedia antes de que requestSchedule devuelva (en el caso de un anuncio previo a la puesta en marcha) se producirá la interrupción previa al contenido del vídeo principal. Debes llamar a play incluso si se produce un error en la función, ya que AdScheduler indicará a MediaPlayer que omita los anuncios y mueva directamente al contenido. Es posible que tenga un requisito empresarial diferente, como insertar un anuncio integrado si un anuncio no se puede capturar correctamente de forma remota.

Durante la reproducción, puedes controlar eventos adicionales que permiten a la aplicación realizar un seguimiento del progreso o los errores que pueden producirse después del proceso inicial de coincidencia de anuncios. El código siguiente muestra algunos de estos eventos, incluidos onPodStart, onPodEnd, onPodCountdown, onAdProgress, onAllComplete y onErrorOccurred.

// Raised when an ad pod starts. Make the countdown timer visible.
myAdScheduler.onPodStart = function (sender, data) {
    myCounterDiv.style.visibility = "visible";
}

// Raised when an ad pod ends. Hide the countdown timer.
myAdScheduler.onPodEnd = function (sender, data) {
    myCounterDiv.style.visibility = "hidden";
}

// Raised when an ad is playing and indicates how many seconds remain  
// in the current pod of ads. This is useful when the app wants to show 
// a visual countdown until the video content resumes.
myAdScheduler.onPodCountdown = function (sender, data) {
    myCounterText = "Content resumes in: " +
    Math.ceil(data.remainingPodTime) + " seconds.";
}

// Raised during each quartile of progress through the ad clip.
myAdScheduler.onAdProgress = function (sender, data) {
}

// Raised when the ads and content are complete.
myAdScheduler.onAllComplete = function (sender) {
}

// Raised when an error occurs during playback after successfully scheduling.
myAdScheduler.onErrorOccurred = function (sender, data) {
}

Miembros de AdScheduler

En esta sección se proporcionan algunos detalles sobre los miembros del objeto AdScheduler . Para obtener más información sobre estos miembros, vea los comentarios y definiciones en el archivo AdScheduler.js del proyecto.

solicitarHorario

Este método solicita una programación de anuncios desde el servidor de anuncios de Microsoft e la inserta en la escala de tiempo de MediaPlayer que se pasó al constructor AdScheduler .

El tercer parámetro opcional (adTags) es una colección JSON de pares nombre-valor que se pueden usar para las aplicaciones que tienen destinos avanzados. Por ejemplo, una aplicación que reproduce una variedad de vídeos relacionados con auto podría complementar el identificador de unidad de anuncio con la marca y el modelo del coche que se muestra. Este parámetro está pensado para que solo los asociados que reciban la aprobación de Microsoft usen etiquetas de anuncios.

Se deben tener en cuenta los siguientes elementos al hacer referencia a adTags:

Este parámetro es una opción muy poco usada. El publicador debe trabajar estrechamente con Microsoft antes de usar adTags.
Tanto los nombres como los valores deben estar predeterminados en el servicio de anuncios. Las etiquetas de anuncios no son palabras clave o términos de búsqueda finalizados abiertos.
El número máximo admitido de etiquetas es 10.
Los nombres de etiqueta están restringidos a 16 caracteres.
Los valores de etiqueta tienen un máximo de 128 caracteres.

solicitarProgramaPorUri

Este método solicita una programación de anuncios del servidor de anuncios que no es de Microsoft especificado en el URI e lo inserta en la escala de tiempo de MediaPlayer que se pasó al constructor AdScheduler . La carga de anuncios que devuelve el servidor de anuncios debe cumplir los formatos de carga de plantilla de servicio de anuncios de vídeo (VAST) o Video Multiple Ad Playlist (VMAP).

mediaTimeout

Esta propiedad obtiene o establece el número de milisegundos que el medio debe reproducirse. Un valor de 0 informa al sistema de que nunca se ha agotado el tiempo de espera. El valor predeterminado es 30000 ms (30 segundos).

reproducirMediosOmitidos

Esta propiedad obtiene o establece un valor booleano que indica si los medios programados se reproducirán si el usuario omite un punto más allá de una hora de inicio programada.

El cliente de anuncios y el reproductor multimedia aplicarán reglas en términos de lo que sucede con los anuncios durante el reenvío rápido y el rebobinado del contenido de vídeo principal. En la mayoría de los casos, los desarrolladores de aplicaciones no permiten omitir completamente los anuncios, pero quieren proporcionar una experiencia razonable para el usuario. Las dos opciones siguientes se encuentran dentro de las necesidades de la mayoría de los desarrolladores:

Permitir que los usuarios finales omitan los pods de anuncios a voluntad.
Permitir a los usuarios omitir los pods de anuncios, pero reproducir el pod más reciente cuando se reanuda la reproducción.

La propiedad playSkippedMedia tiene las siguientes condiciones:

Los anuncios no se pueden omitir ni reenviar rápidamente una vez que comienza el anuncio.
Todos los anuncios de un pod de anuncios se reproducirán una vez que se haya iniciado el pod.
Una vez reproducida, un anuncio no volverá a reproducirse durante el contenido principal (película, episodio, etc.); los marcadores de anuncios se marcarán como reproducidos o eliminados.
No se pueden omitir los anuncios de lanzamiento previo.

Al reanudar el contenido que contiene publicidad, establezca playSkippedMedia en false para omitir los lanzamientos previos y evitar que se reproduzca el salto de anuncio más reciente. Después de iniciar el contenido, establezca playSkippedMedia en true para asegurarse de que los usuarios no puedan avanzar rápidamente a través de anuncios posteriores.

Nota:

Un pod es un grupo de anuncios que se reproducen en una secuencia, como un grupo de anuncios que se reproducen durante un descanso comercial. Para obtener más información, consulte la especificación IAB Digital Video Ad Serving Template (VAST).

requestTimeout

Esta propiedad obtiene o establece el número de milisegundos para esperar una respuesta de solicitud de anuncio antes de que se agote el tiempo de espera. Un valor de 0 informa al sistema de que nunca se ha agotado el tiempo de espera. El valor predeterminado es 30000 ms (30 segundos).

horario

Esta propiedad obtiene los datos de programación recuperados del servidor de anuncios. Este objeto incluye la jerarquía completa de datos que corresponde a la estructura de la plantilla de servicio de anuncios de vídeo (VAST) o video multiple Ad Playlist (VMAP).

onAdProgress

Este evento se genera cuando la reproducción de anuncios alcanza puntos de control cuartiles. El segundo parámetro del controlador de eventos (eventInfo) es un objeto JSON con los miembros siguientes:

progress: el estado de reproducción de anuncios (uno de los valores de enumeración de MediaProgress definidos en AdScheduler.js).
clip: clip de vídeo que se está reproduciéndose. Este objeto no está pensado para usarse en el código.
adPackage: objeto que representa la parte de la carga de anuncios que corresponde al anuncio que se está reproduciendo. Este objeto no está pensado para usarse en el código.

onAllComplete

Este evento se genera cuando el contenido principal llega al final y también finalizan los anuncios posteriores a la puesta en marcha programados.

errorOcurrido

Este evento se genera cuando AdScheduler encuentra un error. Para obtener más información sobre los valores de código de error, vea ErrorCode.

onPodCountdown

Este evento se genera cuando se está reproduciendo un anuncio e indica cuánto tiempo permanece en el pod actual. El segundo parámetro del controlador de eventos (eventData) es un objeto JSON con los miembros siguientes:

remainingAdTime: número de segundos que quedan para el anuncio actual.
remainingPodTime: número de segundos que quedan para el pod actual.

Nota:

onPodEnd

Este evento se genera cuando finaliza un pod de anuncios. El segundo parámetro del controlador de eventos (eventData) es un objeto JSON con los miembros siguientes:

startTime: hora de inicio del pod, en segundos.
pod: objeto que representa el pod. Este objeto no está pensado para usarse en el código.

onPodStart

Este evento se genera cuando se inicia un pod de anuncios. El segundo parámetro del controlador de eventos (eventData) es un objeto JSON con los miembros siguientes:

startTime: hora de inicio del pod, en segundos.
pod: objeto que representa el pod. Este objeto no está pensado para usarse en el código.

Compartir a través de

Mostrar anuncios en contenido de vídeo

Requisitos previos

Cómo usar la clase AdScheduler en el código

Miembros de AdScheduler

solicitarHorario

solicitarProgramaPorUri

mediaTimeout

reproducirMediosOmitidos

requestTimeout

horario

onAdProgress

onAllComplete

errorOcurrido

onPodCountdown

onPodEnd

onPodStart

Comentarios

Recursos adicionales