Afficher des publicités dans du contenu vidéoShow ads in video content

Avertissement

Depuis le 1er juin 2020, la plateforme de monétisation Microsoft AD pour les applications Windows UWP sera arrêtée.As of June 1, 2020, the Microsoft Ad Monetization platform for Windows UWP apps will be shut down. En savoir plusLearn more

Cette procédure pas à pas montre comment utiliser la classe AdScheduler pour afficher les publicités du contenu vidéo dans une application plateforme Windows universelle (UWP) qui a été écrite à l’aide de JavaScript avec 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.

Notes

Cette fonctionnalité n’est actuellement prise en charge que pour les applications UWP écrites à l’aide de JavaScript avec HTML.This feature is currently supported only for UWP apps that are written using JavaScript with HTML.

AdScheduler fonctionne avec les médias à diffusion progressive ou continue et utilise les formats de charge utile standard de l’IAB : VAST (Video Ad Serving Template) 2.0/3.0 et VMAP.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. L’utilisation des normes rend AdScheduler indépendant du service de publicité avec lequel il interagit.By using standards, AdScheduler is agnostic to the ad service with which it interacts.

La publicité pour contenu vidéo varie selon que le programme dure moins de dix minutes (format court) ou plus de dix minutes (format long).Advertising for video content differs based upon whether the program is under ten minutes (short form), or over ten minutes (long form). Bien que ce dernier soit plus difficile à mettre en place au niveau du service, la façon d’écrire le code côté client ne présente en fait aucune différence.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 AdScheduler reçoit une charge utile VAST avec une seule publicité au lieu d’un manifeste, elle est traitée comme si le manifeste appelait une publicité précédant la vidéo (s’arrêtant à 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).

PrérequisPrerequisites

  • Installez le Kit de développement logiciel (SDK) Microsoft Advertising avec Visual Studio 2015 ou une version ultérieure.Install the Microsoft Advertising SDK with Visual Studio 2015 or a later release.

  • Votre projet doit utiliser le contrôle MediaPlayer pour afficher le contenu vidéo dans lequel les publicités doivent apparaître.Your project must use the MediaPlayer control to serve the video content in which the ads will be scheduled. Ce contrôle est disponible dans la collection TVHelpers des bibliothèques mises à la disposition sur GitHub par Microsoft.This control is available in the TVHelpers collection of libraries available from Microsoft on GitHub.

    L’exemple suivant montre comment déclarer un MediaPlayer dans le balisage HTML.The following example shows how to declare a MediaPlayer in HTML markup. En règle générale, ce code appartient à la section <body> du fichier index.html (ou un autre fichier html, selon votre projet).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>
    

    L’exemple suivant montre comment établir un MediaPlayer dans du code 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);
    

Comment utiliser la classe AdScheduler dans votre codeHow to use the AdScheduler class in your code

  1. Dans Visual Studio, ouvrez votre projet ou créez-en un.In Visual Studio, open your project or create a new project.

  2. Si votre projet cible Toute UC, mettez-le à jour pour utiliser une sortie de génération propre à l’architecture (par exemple, x86).If your project targets Any CPU, update your project to use an architecture-specific build output (for example, x86). Si votre projet cible Toute UC, vous ne pourrez pas ajouter une référence à la bibliothèque de publicités Microsoft dans les étapes suivantes.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. Pour plus d’informations, consultez Erreurs de référence provoquées par le ciblage de Toute UC dans votre projet.For more information, see Reference errors caused by targeting Any CPU in your project.

  3. Ajoutez une référence à la bibliothèque du Kit de développement logiciel (SDK) Microsoft Advertising pour JavaScript à votre projet.Add a reference to the Microsoft Advertising SDK for JavaScript library to your project.

    1. Dans la fenêtre Explorateur de solutions , cliquez avec le bouton droit sur références, puis sélectionnez Ajouter une référence...From the Solution Explorer window, right click References, and select Add Reference…
    2. Dans Gestionnaire de références, développez Windows universel, cliquez sur Extensions, puis cochez la case en regard de Kit de développement logiciel (SDK) Microsoft Advertising pour JavaScript (version 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. Dans Gestionnaire de références, cliquez sur OK.In Reference Manager, click OK.
  4. Ajoutez le fichier AdScheduler.js à votre projet :Add the AdScheduler.js file to your project:

    1. Dans Visual Studio, cliquez sur Projet et sur Gérer les packages NuGet.In Visual Studio, click Project and Manage NuGet Packages.
    2. Dans la zone de recherche, tapez Microsoft.StoreServices.VideoAdScheduler, puis installez le package Microsoft.StoreServices.VideoAdScheduler.In the search box, type Microsoft.StoreServices.VideoAdScheduler and install the Microsoft.StoreServices.VideoAdScheduler package. Le fichier AdScheduler.js est ajouté au sous-répertoire .. /js de votre projet.The AdScheduler.js file is added to the ../js subdirectory in your project.
  5. Ouvrez le fichier index.html (ou un autre fichier html en fonction de votre projet).Open the index.html file (or other html file as appropriate for your project). Dans la section <head>, après les références JavaScript des fichiers default.css et main.js du projet, ajoutez la référence à ad.js et 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>
    

    Notes

    Cette ligne doit être placée dans la <head> section après l’inclusion de main.js ; dans le cas contraire, vous rencontrerez une erreur lors de la génération de votre projet.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. Dans le fichier main.js de votre projet, ajoutez le code qui crée un objet AdScheduler.In the main.js file in your project, add code that creates a new AdScheduler object. Transmettez le MediaPlayer qui héberge votre contenu vidéo.Pass in the MediaPlayer that hosts your video content. Le code doit être placé de telle sorte qu’il s’exécute après 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. Utilisez les méthodes requestSchedule ou requestScheduleByUrl de l’objet AdScheduler pour demander une planification ad à partir du serveur, puis insérez-la dans la chronologie de MediaPlayer , puis lisez le support vidéo.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 vous êtes partenaire Microsoft et que vous avez reçu l’autorisation de demander une planification publicitaire auprès du serveur d’annonces Microsoft, utilisez requestSchedule et spécifiez l’ID d’application et l’ID d’unité publicitaire qui vous ont été fournis par votre représentant 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.

      Cette méthode prend la forme d’une promesse, qui est une construction asynchrone où deux pointeurs de fonction sont passés : un pointeur pour la fonction OnComplete à appeler lorsque la promesse se termine avec succès et un pointeur pour la fonction OnError à appeler si une erreur est rencontrée.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. Dans la fonction OnComplete , démarrez la lecture de votre contenu vidéo.In the onComplete function, start playback of your video content. La publicité commence à l’heure planifiée.The ad will start playing at the scheduled time. Dans votre fonction OnError , gérez l’erreur, puis démarrez la lecture de votre vidéo.In your onError function, handle the error and then start playback of your video. Votre contenu vidéo s’exécutera sans publicité.Your video content will play without an ad. L’argument de la fonction OnError est un objet qui contient les membres suivants.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();
        });
      
    • Pour demander une planification ad à partir d’un serveur AD non-Microsoft, utilisez requestScheduleByUrlet transmettez l’URI du serveur.To request an ad schedule from a non-Microsoft ad server, use requestScheduleByUrl, and pass in the server URI. Cette méthode prend également la forme d’une promesse qui accepte des pointeurs pour les fonctions OnComplete et OnError .This method also takes the form of a Promise that accepts pointers for the onComplete and onError functions. La charge utile Active Directory qui est retournée par le serveur doit être conforme au format de charge utile de la vidéo Active Directory (vaste) ou de la sélection de vidéo (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();
        });
      

    Notes

    Vous devez attendre que requestSchedule ou requestScheduleByUrl retourne avant de commencer à lire le contenu vidéo principal dans le MediaPlayer.You should wait for requestSchedule or requestScheduleByUrl to return before starting to play the primary video content in the MediaPlayer. À partir du début de la lecture du média avant que requestSchedule ne retourne (dans le cas d’une publication préliminaire), le pré-roll interrompt le contenu vidéo 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. Vous devez appeler Play même si la fonction échoue, car le AdScheduler indique au MediaPlayer d’ignorer la ou les annonces et de se déplacer directement vers le contenu.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. Vous pouvez avoir une exigence différente, telle que l’insertion d’une publicité intégrée dans le cas où une annonce ne peut pas être récupérée à distance.You may have a different business requirement, such as inserting a built-in ad if an ad can't be successfully fetched remotely.

  8. Pendant la lecture, vous pouvez gérer d’autres événements qui permettent à votre application de suivre la progression et/ou les erreurs susceptibles de se produire après le processus de sélection d’annonce initial.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. Le code suivant contient certains de ces événements, dont onPodStart, onPodEnd, onPodCountdown, onAdProgress, onAllComplete et 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) {
    }
    

Membres AdSchedulerAdScheduler members

Cette section fournit des détails sur les membres de l’objet AdScheduler .This section provides some details about the members of the AdScheduler object. Pour plus d’informations sur ces membres, consultez les commentaires et les définitions dans le fichier AdScheduler.js de votre projet.For more information about these members, see the comments and definitions in the AdScheduler.js file in your project.

requestSchedulerequestSchedule

Cette méthode demande une planification ad à partir du serveur Microsoft ad et l’insère dans la chronologie du MediaPlayer qui a été passé au constructeur 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.

Le troisième paramètre facultatif (adTags) est une collection JSON de paires nom/valeur qui peut être utilisée pour les applications qui ont un ciblage avancé.The optional third paramter (adTags) is a JSON collection of name/value pairs that can be used for apps that have advanced targeting. Par exemple, une application qui joue un grand nombre de vidéos liées automatiquement peut compléter l’ID d’unité ad avec la marque et le modèle de la voiture affichée.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. Ce paramètre est destiné à être utilisé uniquement par les partenaires qui reçoivent l’approbation de Microsoft pour utiliser des balises ad.This parameter is intended to be used only by partners who receive approval from Microsoft to use ad tags.

Les éléments suivants doivent être notés quand vous faites référence à adTags:The following items should be noted when referring to adTags:

  • Ce paramètre est une option très rarement utilisée.This parameter is a very rarely used option. Le serveur de publication doit travailler en étroite collaboration avec Microsoft avant d’utiliser adTags.The publisher must work closely with Microsoft before using adTags.
  • Les noms et les valeurs doivent être prédéterminés sur le service Active Directory.Both the names and the values must be predetermined on the ad service. Les balises ad ne sont pas ouvertes termes de recherche ou Mots clés.Ad tags are not open ended search terms or keywords.
  • Le nombre maximal de balises prises en charge est de 10.The maximum supported number of tags is 10.
  • Les noms de balises sont limités à 16 caractères.Tag names are restricted to 16 characters.
  • Les valeurs des balises ne doivent pas dépasser 128 caractères.Tag values have a maximum of 128 characters.

requestScheduleByUrirequestScheduleByUri

Cette méthode demande une planification ad à partir du serveur AD non-Microsoft spécifié dans l’URI et l’insère dans la chronologie du MediaPlayer qui a été passé au constructeur 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 charge utile Active Directory qui est retournée par le serveur Active Directory doit être conforme au format de charge utile de la vidéo Active Directory (vaste) ou de la sélection de vidéo (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

Cette propriété obtient ou définit le nombre de millisecondes pendant lesquelles le média doit être lisible.This property gets or sets the number of milliseconds that the media must be playable. La valeur 0 indique au système de ne jamais avoir expiré.A value of 0 informs the system to never timeout. La valeur par défaut est 30000 ms (30 secondes).The default is 30000 ms (30 seconds).

playSkippedMediaplaySkippedMedia

Cette propriété obtient ou définit une valeur booléenne qui indique si le média planifié est lu si l’utilisateur avance jusqu’à un point situé après une heure de début planifiée.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.

Le client Active Directory et le lecteur multimédia appliquent les règles en termes de publication pendant le transfert rapide et le rembobinage du contenu vidéo 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. Dans la plupart des cas, les développeurs d’applications n’autorisent pas l’ignorance complète des publications, mais elles souhaitent fournir une expérience raisonnable à l’utilisateur.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. Les deux options suivantes répondent aux besoins de la plupart des développeurs :The following two options fall within the needs of most developers:

  1. Autorisez les utilisateurs finaux à ignorer les modules de publication à l’adresse.Allow end-users to skip over advertisement pods at will.
  2. Autorisez les utilisateurs à ignorer les gousses de publication, mais à lire le bloc le plus récent lors de la reprise de la lecture.Allow users to skip over advertisement pods but play the most recent pod when playback resumes.

La propriété playSkippedMedia a les conditions suivantes :The playSkippedMedia property has the following conditions:

  • Les publications ne peuvent pas être ignorées ou transmises rapidement après le début de la publication.Advertisements cannot be skipped or fast forwarded once the advertisement begins.
  • Toutes les publications dans un pod de publication sont lues une fois que le POD a démarré.All advertisements in an advertisement pod will play once the pod has started.
  • Une fois jouée, une publication n’est pas lue pendant le contenu principal (film, épisode, etc.); les marqueurs de publication sont marqués comme lus ou supprimés.Once played, an advertisement will not play again during the primary content (movie, episode, etc.); advertisement markers will be marked as played or removed.
  • Les publications de pré-déploiement ne peuvent pas être ignorées.Pre-rollout advertisements cannot be skipped.

Quand vous reprenez du contenu contenant des publicités, définissez playSkippedMedia sur false pour ignorer les présélections et empêcher la dernière exécution de la dernière.When resuming content that contains advertising, set playSkippedMedia to false to skip pre-rolls and prevent the most recent ad break from playing. Ensuite, une fois le contenu démarré, affectez à playSkippedMedia la valeur true pour vous assurer que les utilisateurs ne peuvent pas avancer rapidement par le biais de publicités ultérieures.Then, after the content starts, set playSkippedMedia to true to ensure that users cannot fast-forward through subsequent ads.

Notes

Un Pod est un groupe de publicités qui s’exécutent dans une séquence, par exemple un groupe de publicités qui s’exécutent pendant une pause commerciale.A pod is a group of ads that play in a sequence, such as a group of ads that play during a commercial break. Pour plus d’informations, consultez la spécification du modèle de service d’annonces numériques de l’IAB.For more details, see the IAB Digital Video Ad Serving Template (VAST) specification.

requestTimeoutrequestTimeout

Cette propriété obtient ou définit le nombre de millisecondes d’attente d’une réponse de demande Active Directory avant le dépassement du délai d’attente. La valeur 0 indique au système de ne jamais avoir expiré.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. La valeur par défaut est 30000 ms (30 secondes).The default is 30000 ms (30 seconds).

scheduleschedule

Cette propriété obtient les données de planification qui ont été récupérées à partir du serveur AD.This property gets the schedule data that was retrieved from the ad server. Cet objet comprend la hiérarchie complète des données qui correspond à la structure du modèle de service vidéo (vaste) ou à la charge utile de la playlist de vidéo multiple ad (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

Cet événement est déclenché lorsque la lecture Active Directory atteint les points de contrôle du quartile.This event is raised when ad playback reaches quartile checkpoints. Le deuxième paramètre du gestionnaire d’événements (EventInfo) est un objet JSON avec les membres suivants :The second parameter of the event handler (eventInfo) is a JSON object with the following members:

  • Progress: état de la lecture ad (l’une des valeurs d’énumération MediaProgress définie dans AdScheduler.js).progress: The ad playback status (one of the MediaProgress enum values defined in AdScheduler.js).
  • clip: le clip vidéo en cours de lecture.clip: The video clip that is being played. Cet objet n’est pas destiné à être utilisé dans votre code.This object is not intended to be used in your code.
  • adPackage: objet qui représente la partie de la charge active ad qui correspond à la publicité en cours de diffusion.adPackage: An object that represents the part of the ad payload that corresponds to the ad that is playing. Cet objet n’est pas destiné à être utilisé dans votre code.This object is not intended to be used in your code.

onAllCompleteonAllComplete

Cet événement est déclenché lorsque le contenu principal atteint la fin et que toute publicité postérieure à la planification est également terminée.This event is raised when the main content reaches the end and any scheduled post-roll ads are also ended.

onErrorOccurredonErrorOccurred

Cet événement est déclenché lorsque le AdScheduler rencontre une erreur.This event is raised when the AdScheduler encounters an error. Pour plus d’informations sur les valeurs des codes d’erreur, consultez ErrorCode.For more information about the error code values, see ErrorCode.

onPodCountdownonPodCountdown

Cet événement est déclenché lorsqu’une publicité est lue et indique le temps restant dans le pod actuel.This event is raised when an ad is playing and indicates how much time remains in the current pod. Le deuxième paramètre du gestionnaire d’événements (EventData) est un objet JSON avec les membres suivants :The second parameter of the event handler (eventData) is a JSON object with the following members:

  • remainingAdTime: nombre de secondes restantes pour la publicité active.remainingAdTime: The number of seconds left for the current ad.
  • remainingPodTime: nombre de secondes restantes pour le pod actuel.remainingPodTime: The number of seconds left for the current pod.

Notes

Un Pod est un groupe de publicités qui s’exécutent dans une séquence, par exemple un groupe de publicités qui s’exécutent pendant une pause commerciale.A pod is a group of ads that play in a sequence, such as a group of ads that play during a commercial break. Pour plus d’informations, consultez la spécification du modèle de service d’annonces numériques de l’IAB.For more details, see the IAB Digital Video Ad Serving Template (VAST) specification.

onPodEndonPodEnd

Cet événement est déclenché lorsqu’un bloc publicitaire se termine.This event is raised when an ad pod ends. Le deuxième paramètre du gestionnaire d’événements (EventData) est un objet JSON avec les membres suivants :The second parameter of the event handler (eventData) is a JSON object with the following members:

  • StartTime: l’heure de début du Pod, en secondes.startTime: The pod's start time, in seconds.
  • Pod: objet qui représente le POD.pod: An object that represents the pod. Cet objet n’est pas destiné à être utilisé dans votre code.This object is not intended to be used in your code.

onPodStartonPodStart

Cet événement est déclenché lors du démarrage d’un pod.This event is raised when an ad pod starts. Le deuxième paramètre du gestionnaire d’événements (EventData) est un objet JSON avec les membres suivants :The second parameter of the event handler (eventData) is a JSON object with the following members:

  • StartTime: l’heure de début du Pod, en secondes.startTime: The pod's start time, in seconds.
  • Pod: objet qui représente le POD.pod: An object that represents the pod. Cet objet n’est pas destiné à être utilisé dans votre code.This object is not intended to be used in your code.