Mostrar anuncios en contenido de vídeoShow ads in video content

Advertencia

A partir del 1 de junio de 2020, se cerrará la plataforma de monetización de Microsoft ad para aplicaciones UWP de Windows.As of June 1, 2020, the Microsoft Ad Monetization platform for Windows UWP apps will be shut down. Más informaciónLearn more

En este tutorial se muestra cómo usar la clase AdScheduler para mostrar anuncios en el contenido de vídeo en una aplicación plataforma universal de Windows (UWP) que se escribió con JavaScript con HTML.This walkthrough shows how to use the AdScheduler class to show ads in video content in a Universal Windows Platform (UWP) app that was written using JavaScript with HTML.

Nota

Actualmente, esta característica solo se admite para las aplicaciones para UWP escritas con JavaScript con HTML.This feature is currently supported only for UWP apps that are written using JavaScript with HTML.

AdScheduler funciona tanto con contenido multimedia progresivo como de streaming y utiliza los formatos de carga Video Ad Serving Template (VAST) 2.0/3.0 y VMAP estándar de IAB.AdScheduler works with both progressive and streaming media, and uses IAB standard Video Ad Serving Template (VAST) 2.0/3.0 and VMAP payload formats. Al usar estándares, AdScheduler es independiente del servicio de anuncios con el que interactúa.By using standards, AdScheduler is agnostic to the ad service with which it interacts.

La publicidad para el contenido de vídeo es diferente en función de si el programa es inferior a 10 minutos (formato corto) o superior a 10 minutos (formato largo).Advertising for video content differs based upon whether the program is under ten minutes (short form), or over ten minutes (long form). Aunque la segunda opción es más complicada de configurar en el servicio, realmente no existe ninguna diferencia en cómo se escribe el código del lado cliente.Although the latter is more complicated to set up on the service, there is actually no difference in how one writes the client side code. Si la clase AdScheduler recibe una carga de VAST con un solo anuncio en lugar de un manifiesto, esto se trata como si el manifiesto llamara a un solo anuncio ya preparado (un salto en el minuto 00:00).If the AdScheduler receives a VAST payload with a single ad instead of a manifest, it is treated as if the manifest called for a single pre-roll ad (one break at time 00:00).

Requisitos previosPrerequisites

  • Instale el SDK de Microsoft Advertising con Visual Studio 2015 o una versión posterior.Install the Microsoft Advertising SDK with Visual Studio 2015 or a later release.

  • El proyecto debe usar el control MediaPlayer para proporcionar el contenido de vídeo en el que se programarán los anuncios.Your project must use the MediaPlayer control to serve the video content in which the ads will be scheduled. Este control está disponible en la colección de bibliotecas TVHelpers disponible a través de Microsoft en GitHub.This control is available in the TVHelpers collection of libraries available from Microsoft on GitHub.

    En el siguiente ejemplo se muestra cómo declarar un control MediaPlayer en formato HTML.The following example shows how to declare a MediaPlayer in HTML markup. Por lo general, este formato se incluye en la sección <body> en el archivo index.html (u otro archivo HTML, según corresponda al proyecto).Typically, this markup belongs in the <body> section in the index.html file (or another html file as appropriate for your project).

    <div id="MediaPlayerDiv" data-win-control="TVJS.MediaPlayer">
      <video src="URL to your content">
      </video>
    </div>
    

    En el siguiente ejemplo se muestra cómo establecer un control MediaPlayer en código JavaScript.The following example shows how to establish a MediaPlayer in JavaScript code.

    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ódigoHow to use the AdScheduler class in your code

  1. En Visual Studio, abre el proyecto o crea uno nuevo.In Visual Studio, open your project or create a new project.

  2. Si el destino del proyecto es Cualquier CPU, actualiza el proyecto para que use una salida de compilación específica por arquitectura (por ejemplo, x86).If your project targets Any CPU, update your project to use an architecture-specific build output (for example, x86). Si el destino del proyecto es Cualquier CPU, no podrás agregar una referencia a la biblioteca de publicidad de Microsoft correctamente a través de los siguientes pasos.If your project targets Any CPU, you will not be able to successfully add a reference to the Microsoft advertising library in the following steps. Para obtener más información, consulta Errores de referencia derivados de orientar el proyecto a Cualquier CPU.For more information, see Reference errors caused by targeting Any CPU in your project.

  3. Agrega a tu proyecto una referencia a la biblioteca Microsoft Advertising SDK for JavaScript.Add a reference to the Microsoft Advertising SDK for JavaScript library to your project.

    1. En la ventana de Explorador de soluciones , haga clic con el botón derecho en referenciasy seleccione Agregar referencia.. .From the Solution Explorer window, right click References, and select Add Reference…
    2. En el Administrador de referencias, expande Universal Windows, haz clic en Extensiones y, después, selecciona la casilla junto a Microsoft Advertising SDK for JavaScript (versión 10.0).In Reference Manager, expand Universal Windows, click Extensions, and then select the check box next to Microsoft Advertising SDK for JavaScript (Version 10.0).
    3. En el Administrador de referencias, haz clic en Aceptar.In Reference Manager, click OK.
  4. Agrega el archivo AdScheduler.js al proyecto:Add the AdScheduler.js file to your project:

    1. En Visual Studio, haz clic en Proyecto y luego en Administrar paquetes de NuGet.In Visual Studio, click Project and Manage NuGet Packages.
    2. En el cuadro de búsqueda, escribe Microsoft.StoreServices.VideoAdScheduler e instala el paquete Microsoft.StoreServices.VideoAdScheduler.In the search box, type Microsoft.StoreServices.VideoAdScheduler and install the Microsoft.StoreServices.VideoAdScheduler package. El archivo AdScheduler.js se agrega al subdirectorio .. /js en el proyecto.The AdScheduler.js file is added to the ../js subdirectory in your project.
  5. Abre el archivo index.html (u otro archivo html adecuado para el proyecto).Open the index.html file (or other html file as appropriate for your project). En la sección <head>, después de las referencias de JavaScript del proyecto de default.css y main.js, agrega la referencia a ad.js y adscheduler.js.In the <head> section, after the project’s JavaScript references of default.css and main.js, add the reference to ad.js and adscheduler.js.

    <script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
    <script src="/js/adscheduler.js"></script>
    

    Nota

    Esta línea se debe colocar en la <head> sección después de la inclusión de main.js; de lo contrario, se producirá un error al compilar el proyecto.This line must be placed in the <head> section after the include of main.js; otherwise, you will encounter an error when you build your project.

  6. En el archivo main.js del proyecto, agrega código que cree un nuevo objeto AdScheduler.In the main.js file in your project, add code that creates a new AdScheduler object. Pasa el objeto MediaPlayer que hospeda el contenido de vídeo.Pass in the MediaPlayer that hosts your video content. El código debe colocarse de forma que se ejecute después de WinJS.UI.processAll.The code must be placed so that it runs after WinJS.UI.processAll.

    var myMediaPlayer = document.getElementById("MediaPlayerDiv");
    var myAdScheduler = new MicrosoftNSJS.Advertising.AdScheduler(myMediaPlayer);
    
  7. Use los métodos requestSchedule o RequestScheduleByUrl del objeto AdScheduler para solicitar una programación de ad del servidor e insértela en la escala de tiempo de MediaPlayer y, a continuación, reproduzca el medio de vídeo.Use the requestSchedule or requestScheduleByUrl methods of the AdScheduler object to request an ad schedule from the server and insert it into the MediaPlayer timeline, and then play the video media.

    • Si eres un asociado de Microsoft que ha recibido permiso para solicitar una programación de anuncios del servidor de anuncios de Microsoft, usa requestSchedule y especifica el identificador de aplicación y el identificador de unidad de anuncios que te haya proporcionado tu representante de Microsoft.If you are a Microsoft partner who has received permission to request an ad schedule from the Microsoft ad server, use requestSchedule and specify the application ID and ad unit ID that were provided to you by your Microsoft representative.

      Este método toma la forma de una promesa, que es una construcción asincrónica donde se pasan dos punteros de función: un puntero a la función alcompletar para llamar a cuando la promesa se completa correctamente y un puntero para que la función OnError llame a si se produce un error.This method takes the form of a Promise, which is an asynchronous construct where two function pointers are passed: a pointer for the onComplete function to call when the promise completes successfully and a pointer for the onError function to call if an error is encountered. En la función Alfinalizar , inicie la reproducción del contenido de vídeo.In the onComplete function, start playback of your video content. El anuncio comenzará a reproducirse a la hora programada.The ad will start playing at the scheduled time. En la función OnError , controle el error y, a continuación, inicie la reproducción del vídeo.In your onError function, handle the error and then start playback of your video. El contenido de vídeo se reproducirá sin un anuncio.Your video content will play without an ad. El argumento de la función OnError es un objeto que contiene los miembros siguientes.The argument of the onError function is an object that contains the following members.

      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 ad de un servidor de ad que no sea de Microsoft, use requestScheduleByUrly pase el URI del servidor.To request an ad schedule from a non-Microsoft ad server, use requestScheduleByUrl, and pass in the server URI. Este método también toma la forma de una promesa que acepta punteros para las funciones Alfinalizar y OnError .This method also takes the form of a Promise that accepts pointers for the onComplete and onError functions. La carga de ad que se devuelve desde el servidor debe ajustarse a los formatos de carga de la plantilla de servicio de anuncios de vídeo (VAST) o vídeo de varias listas de reproducción (VMAP).The ad payload that is returned from the server must conform to the Video Ad Serving Template (VAST) or Video Multiple Ad Playlist (VMAP) payload formats.

      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

    Debe esperar a que se devuelvan requestSchedule o requestScheduleByUrl antes de empezar a reproducir el contenido de vídeo principal en el MediaPlayer.You should wait for requestSchedule or requestScheduleByUrl to return before starting to play the primary video content in the MediaPlayer. A partir de la reproducción de medios antes de que requestSchedule devuelva (en el caso de un anuncio de relanzamiento), la reversión previa interrumpirá el contenido del vídeo principal.Starting to play media before requestSchedule returns (in the case of a pre-roll advertisement) will result in the pre-roll interrupting the primary video content. Debe llamar a Replay incluso si se produce un error en la función, porque el AdScheduler indicará a la MediaPlayer que omita los anuncios y se desplace directamente al contenido.You must call play even if the function fails, because the AdScheduler will tell the MediaPlayer to skip the ad(s) and move straight to the content. Puede que tengas un requisito de negocio distinto, como insertar un anuncio integrado si no es posible obtener un anuncio de forma remota.You may have a different business requirement, such as inserting a built-in ad if an ad can't be successfully fetched remotely.

  8. Durante la reproducción, puedes controlar eventos adicionales que permiten a tu aplicación realizar el seguimiento del progreso o los errores que pueden producirse tras el proceso de coincidencia de anuncios inicial.During playback, you can handle additional events that let your app track progress and/or errors which may occur after the initial ad matching process. El siguiente código muestra algunos de estos eventos, incluidos onPodStart, onPodEnd, onPodCountdown, onAdProgress, onAllComplete y onErrorOccurred.The following code shows some of these events, including onPodStart, onPodEnd, onPodCountdown, onAdProgress, onAllComplete, and 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 AdSchedulerAdScheduler members

En esta sección se proporcionan algunos detalles sobre los miembros del objeto AdScheduler .This section provides some details about the members of the AdScheduler object. Para obtener más información sobre estos miembros, vea los comentarios y las definiciones en el archivo AdScheduler.js del proyecto.For more information about these members, see the comments and definitions in the AdScheduler.js file in your project.

requestSchedulerequestSchedule

Este método solicita una programación de ad del servidor de Microsoft ad y la inserta en la escala de tiempo del objeto MediaPlayer que se pasó al constructor AdScheduler .This method requests an ad schedule from the Microsoft ad server and inserts it into the timeline of the MediaPlayer that was passed to the AdScheduler constructor.

El tercer parámetro opcional (adTags) es una colección JSON de pares nombre-valor que se puede usar para las aplicaciones que tienen destinatarios avanzados.The optional third paramter (adTags) is a JSON collection of name/value pairs that can be used for apps that have advanced targeting. Por ejemplo, una aplicación que reproduzca una variedad de vídeos relacionados automáticamente podría complementar el identificador de la unidad de anuncio con la marca y el modelo del coche que se muestra.For example, an app that plays a variety of auto-related videos might supplement the ad unit ID with the make and model of the car being shown. Este parámetro está pensado para que lo usen únicamente los asociados que reciben la aprobación de Microsoft para usar etiquetas de ad.This parameter is intended to be used only by partners who receive approval from Microsoft to use ad tags.

Los siguientes elementos deben indicarse al hacer referencia a adTags:The following items should be noted when referring to adTags:

  • Este parámetro es una opción muy rara vez utilizada.This parameter is a very rarely used option. El publicador debe trabajar en estrecha colaboración con Microsoft antes de usar adTags.The publisher must work closely with Microsoft before using adTags.
  • Tanto los nombres como los valores deben estar predeterminados en el servicio de ad.Both the names and the values must be predetermined on the ad service. Las etiquetas de ad no están abiertas, términos o palabras clave de búsqueda.Ad tags are not open ended search terms or keywords.
  • El número máximo admitido de etiquetas es 10.The maximum supported number of tags is 10.
  • Los nombres de etiqueta están limitados a 16 caracteres.Tag names are restricted to 16 characters.
  • Los valores de etiqueta tienen un máximo de 128 caracteres.Tag values have a maximum of 128 characters.

requestScheduleByUrirequestScheduleByUri

Este método solicita una programación de ad del servidor que no es de Microsoft ad especificado en el URI y lo inserta en la escala de tiempo del objeto MediaPlayer que se pasó al constructor AdScheduler .This method requests an ad schedule from the non-Microsoft ad server specified in the URI and inserts it into the timeline of the MediaPlayer that was passed to the AdScheduler constructor. La carga de ad que devuelve el servidor de ad debe ajustarse a los formatos de carga de vídeo de la plantilla de servicio de anuncios de vídeo (VAST) o vídeo de varias listas de reproducción (VMAP).The ad payload that is returned by the ad server must conform to the Video Ad Serving Template (VAST) or Video Multiple Ad Playlist (VMAP) payload formats.

mediaTimeoutmediaTimeout

Esta propiedad obtiene o establece el número de milisegundos que se debe reproducir el medio.This property gets or sets the number of milliseconds that the media must be playable. Un valor de 0 informa al sistema de que nunca se agota el tiempo de espera.A value of 0 informs the system to never timeout. El valor predeterminado es 30000 MS (30 segundos).The default is 30000 ms (30 seconds).

playSkippedMediaplaySkippedMedia

Esta propiedad obtiene o establece un valor booleano que indica si los medios programados se reproducirán si el usuario se salta a un punto más allá de la hora de inicio programada.This property gets or sets a Boolean value that indicates whether scheduled media will play if user skips ahead to a point past a scheduled start time.

El cliente de AD y el reproductor de media aplicarán reglas en términos de lo que ocurre con los anuncios durante el reenvío rápido y el rebobinado del contenido del vídeo principal.The ad client and media player will enforce rules in terms what happens to advertisements during fast forwarding and rewinding of the primary video content. En la mayoría de los casos, los desarrolladores de aplicaciones no permiten omitir los anuncios por completo, pero quieren proporcionar una experiencia razonable para el usuario.In most cases, app developers do not allow advertisements to be entirely skipped over but do want to provide a reasonable experience for the user. Las dos opciones siguientes se encuentran dentro de las necesidades de la mayoría de los desarrolladores:The following two options fall within the needs of most developers:

  1. Permitir a los usuarios finales omitir los pods de anuncios en lo que se requiera.Allow end-users to skip over advertisement pods at will.
  2. Permitir a los usuarios omitir los pods de anuncios pero reproducir el POD más reciente cuando se reanude la reproducción.Allow users to skip over advertisement pods but play the most recent pod when playback resumes.

La propiedad playSkippedMedia tiene las siguientes condiciones:The playSkippedMedia property has the following conditions:

  • Los anuncios no se pueden omitir ni reenviar rápidamente una vez que se inicia el anuncio.Advertisements cannot be skipped or fast forwarded once the advertisement begins.
  • Todos los anuncios de un pod de anuncio se reproducirán una vez que se haya iniciado el POD.All advertisements in an advertisement pod will play once the pod has started.
  • Una vez jugado, un anuncio no se reproducirá de nuevo durante el contenido principal (película, episodio, etc.); los marcadores de anuncio se marcarán como reproducidos o eliminados.Once played, an advertisement will not play again during the primary content (movie, episode, etc.); advertisement markers will be marked as played or removed.
  • Los anuncios anteriores al lanzamiento no se pueden omitir.Pre-rollout advertisements cannot be skipped.

Al reanudar el contenido que contiene publicidad, establezca playSkippedMedia en false para omitir las reversiones previas y evitar que se reproduzca la interrupción más reciente del anuncio.When resuming content that contains advertising, set playSkippedMedia to false to skip pre-rolls and prevent the most recent ad break from playing. Después, después de que se inicie el contenido, establezca playSkippedMedia en true para asegurarse de que los usuarios no puedan avanzar rápidamente a través de los anuncios posteriores.Then, after the content starts, set playSkippedMedia to true to ensure that users cannot fast-forward through subsequent ads.

Nota

Un POD es un grupo de anuncios que se reproducen en una secuencia, como un grupo de anuncios que se reproducen durante una pausa comercial.A pod is a group of ads that play in a sequence, such as a group of ads that play during a commercial break. Para obtener más información, consulte la especificación de la plantilla de anuncio de vídeo digital de IAB (VAST).For more details, see the IAB Digital Video Ad Serving Template (VAST) specification.

requestTimeoutrequestTimeout

Esta propiedad obtiene o establece el número de milisegundos que se debe esperar una respuesta de solicitud de ad antes de que se agote el tiempo de espera. Un valor de 0 informa al sistema de que nunca se agota el tiempo de espera.This property gets or sets the number of milliseconds to wait for an ad request response before timing out. A value of 0 informs the system to never timeout. El valor predeterminado es 30000 MS (30 segundos).The default is 30000 ms (30 seconds).

scheduleschedule

Esta propiedad obtiene los datos de programación recuperados del servidor de ad.This property gets the schedule data that was retrieved from the ad server. Este objeto incluye la jerarquía completa de datos que corresponde a la estructura de la carga de vídeo de la plantilla de servicio de anuncios de vídeo (VAST) o de vídeo de varias listas de reproducción de anuncios (VMAP).This object includes the full hierarchy of data that corresponds to the structure of the Video Ad Serving Template (VAST) or Video Multiple Ad Playlist (VMAP) payload.

onAdProgressonAdProgress

Este evento se desencadena cuando la reproducción de anuncios alcanza los puntos de control del cuartil.This event is raised when ad playback reaches quartile checkpoints. El segundo parámetro del controlador de eventos (eventInfo) es un objeto JSON con los siguientes miembros:The second parameter of the event handler (eventInfo) is a JSON object with the following members:

  • progreso: el estado de reproducción de ad (uno de los valores de enumeración MediaProgress definidos en AdScheduler.js).progress: The ad playback status (one of the MediaProgress enum values defined in AdScheduler.js).
  • clip: clip de vídeo que se está reproduciendo.clip: The video clip that is being played. Este objeto no está pensado para usarse en el código.This object is not intended to be used in your code.
  • adPackage: un objeto que representa la parte de la carga de ad que corresponde al anuncio que se está reproduciendo.adPackage: An object that represents the part of the ad payload that corresponds to the ad that is playing. Este objeto no está pensado para usarse en el código.This object is not intended to be used in your code.

onAllCompleteonAllComplete

Este evento se desencadena cuando el contenido principal alcanza el final y también finalizan los anuncios post-Roll programados.This event is raised when the main content reaches the end and any scheduled post-roll ads are also ended.

onErrorOccurredonErrorOccurred

Este evento se desencadena cuando AdScheduler detecta un error.This event is raised when the AdScheduler encounters an error. Para obtener más información sobre los valores del código de error, vea ErrorCode.For more information about the error code values, see ErrorCode.

onPodCountdownonPodCountdown

Este evento se desencadena cuando se está reproduciendo un anuncio e indica cuánto tiempo queda en el POD actual.This event is raised when an ad is playing and indicates how much time remains in the current pod. El segundo parámetro del controlador de eventos (eventData) es un objeto JSON con los siguientes miembros:The second parameter of the event handler (eventData) is a JSON object with the following members:

  • remainingAdTime: el número de segundos que quedan para el anuncio actual.remainingAdTime: The number of seconds left for the current ad.
  • remainingPodTime: el número de segundos que quedan para el POD actual.remainingPodTime: The number of seconds left for the current pod.

Nota

Un POD es un grupo de anuncios que se reproducen en una secuencia, como un grupo de anuncios que se reproducen durante una pausa comercial.A pod is a group of ads that play in a sequence, such as a group of ads that play during a commercial break. Para obtener más información, consulte la especificación de la plantilla de anuncio de vídeo digital de IAB (VAST).For more details, see the IAB Digital Video Ad Serving Template (VAST) specification.

onPodEndonPodEnd

Este evento se desencadena cuando finaliza un pod de ad.This event is raised when an ad pod ends. El segundo parámetro del controlador de eventos (eventData) es un objeto JSON con los siguientes miembros:The second parameter of the event handler (eventData) is a JSON object with the following members:

  • startTime: la hora de inicio del Pod, en segundos.startTime: The pod's start time, in seconds.
  • Pod: un objeto que representa el POD.pod: An object that represents the pod. Este objeto no está pensado para usarse en el código.This object is not intended to be used in your code.

onPodStartonPodStart

Este evento se desencadena cuando se inicia un pod de ad.This event is raised when an ad pod starts. El segundo parámetro del controlador de eventos (eventData) es un objeto JSON con los siguientes miembros:The second parameter of the event handler (eventData) is a JSON object with the following members:

  • startTime: la hora de inicio del Pod, en segundos.startTime: The pod's start time, in seconds.
  • Pod: un objeto que representa el POD.pod: An object that represents the pod. Este objeto no está pensado para usarse en el código.This object is not intended to be used in your code.