AdControl en HTML 5 et JavaScript

  • Article

Avertissement

À compter du 1er juin 2020, la plateforme Microsoft Ad Monetization pour les applications Windows UWP sera arrêtée. En savoir plus

Cette procédure pas à pas montre comment utiliser la classe AdControl pour afficher des bannières publicitaires dans une application JavaScript/HTML plateforme Windows universelle (UWP) pour Windows 10 et Windows 11.

Pour un exemple de projet complet illustrant l’ajout de bannières publicitaires à une application HTML/JavaScript, voir Exemples de publicité sur GitHub.

Prérequis

  • Installez le SDK Microsoft Advertising avec Visual Studio 2015 ou une version ultérieure de Visual Studio. Pour obtenir des instructions d’installation, consultez cet article.

Notes

Si vous avez installé la version 10.0.14393 du SDK Windows 10 (mise à jour anniversaire) ou une version ultérieure du Kit de développement logiciel (SDK) Windows, vous devez également installer la bibliothèque WinJS. Cette bibliothèque était auparavant incluse dans les versions précédentes du Kit de développement logiciel (SDK) Windows pour Windows 10, mais à compter de la version 10.0.14393 du SDK Windows 10 (mise à jour anniversaire), cette bibliothèque doit être installée séparément.

Intégrer une bannière publicitaire à votre application

  1. Dans Visual Studio, ouvrez votre projet ou créez-en un.

    Notes

    Si vous utilisez un projet existant, ouvrez le fichier Package.appxmanifest dans votre projet et vérifiez que la fonctionnalité Internet (client) est sélectionnée. Votre application a besoin de cette fonctionnalité pour recevoir des annonces de test et des publicités en direct.

  2. Si votre projet cible Toute UC, mettez-le à jour pour utiliser une sortie de génération propre à l’architecture (par exemple, 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. Pour plus d’informations, consultez Erreurs de référence provoquées par le ciblage de Toute UC dans votre projet.

  3. Ajoutez une référence au SDK Microsoft Advertising dans votre projet :

    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...
    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).
    3. Dans Gestionnaire de références, cliquez sur OK.

  4. Ouvrez le fichier index.html (ou un autre fichier html en fonction de votre projet).

  5. Dans la <section principale> , après les références JavaScript du projet de default.css et de main.js, ajoutez la référence à ad.js.

    <!-- Advertising required references -->
<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>

    Notes

    Cette ligne doit être placée dans la <section principale> après l’inclure de main.js ; sinon, vous rencontrerez une erreur lors de la génération de votre projet.

  6. Modifiez la <section corps> dans le fichier default.html (ou tout autre fichier html approprié pour votre projet) afin d’inclure la div pour AdControl. Affectez les propriétés applicationId et adUnitIdd’AdControl aux valeurs d’unité de test de la publicité. Ajustez également la hauteur et la largeur pour que le contrôle soit l’une des tailles d’annonces prises en charge pour les bannières publicitaires.

    Notes

    Chaque AdControl a une unité publicitaire correspondante qui est utilisée par nos services pour diffuser des publicités au contrôle, et chaque unité publicitaire se compose d’un ID d’unité publicitaire et d’un IDd’application. Dans ces étapes, vous affectez des valeurs d’ID d’unité publicitaire et d’ID d’application de test à votre contrôle. Ces valeurs de test ne peuvent être utilisées que dans une version de test de votre application. Avant de publier votre application dans le Store, vous devez remplacer ces valeurs de test par des valeurs actives de l’Espace partenaires.

    <div id="myAd" style="position: absolute; top: 50px; left: 0px; width: 300px; height: 250px; z-index: 1"
    data-win-control="MicrosoftNSJS.Advertising.AdControl"
    data-win-options="{applicationId: '3f83fe91-d6be-434d-a0ae-7351c5a997f1', adUnitId: 'test'}">
</div>

  7. Compilez et exécutez l’application pour la voir avec une publicité.

L’exemple suivant montre la index.html complète pour une application simple.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>AdControlExampleApp</title>
    <!-- WinJS references -->
    <link href="lib/winjs-4.0.1/css/ui-light.css" rel="stylesheet" />
    <script src="lib/winjs-4.0.1/js/base.js"></script>
    <script src="lib/winjs-4.0.1/js/ui.js"></script>
    <!-- AdControlExampleApp references -->
    <link href="css/default.css" rel="stylesheet" />
    <script src="js/main.js"></script>
    <!-- Required reference for AdControl -->
    <script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
</head>
<body>
    <div id="myAd" style="position: absolute; top: 50px; left: 0px; width: 300px; height: 250px; z-index: 1"
      data-win-control="MicrosoftNSJS.Advertising.AdControl"
      data-win-options="{applicationId: '3f83fe91-d6be-434d-a0ae-7351c5a997f1', adUnitId: 'test'}">
    </div>
    <p>Content goes here</p>
</body>
</html>

Créer un AdControl par programmation dans JavaScript

Les étapes précédentes montrent comment déclarer un AdControl dans votre balisage HTML. Vous pouvez également créer un AdControl par programmation à l’aide de JavaScript. Cet exemple suppose que vous utilisez un div existant dans votre code HTML avec l’ID myAd.

var adDiv = document.getElementById("myAd");
var myAdControl = new MicrosoftNSJS.Advertising.AdControl(adDiv,
{
    applicationId: "3f83fe91-d6be-434d-a0ae-7351c5a997f1",
    adUnitId: "test",
});

myAdControl.isAutoRefreshEnabled = false;
myAdControl.onErrorOccurred = myAdError;
myAdControl.onAdRefreshed = myAdRefreshed;
myAdControl.onEngagedChanged = myAdEngagedChanged;

Cet exemple suppose que vous avez déjà déclaré les méthodes de gestionnaires d’événements myAdError, myAdRefreshed et myAdEngagedChanged.

Si vous utilisez ce code et que vous ne voyez pas de publicités, vous pouvez essayer d’insérer un attribut de position:relative dans l’élément div qui contient le AdControl. Cela remplace le paramètre par défaut de l’élément IFrame. Les publicités apparaissent correctement, sauf si elles ne sont pas affichées en raison de la valeur de cet attribut. Notez que les nouvelles unités publicitaires peuvent ne pas être disponibles pendant 30 minutes.

Notes

Les valeurs applicationId et adUnitId indiquées dans cet exemple sont des valeurs en mode test. Vous devez remplacer ces valeurs par des valeurs actives de l’Espace partenaires avant d’envoyer votre application pour soumission.

Publier votre application avec des publicités en direct

  1. Assurez-vous que votre utilisation des bannières publicitaires dans votre application suit nos instructions pour les bannières publicitaires.

  2. Dans l’Espace partenaires, accédez à la page Annonces in-app et créez une unité publicitaire. Pour le type d’unité publicitaire, spécifiez Bannière. Prenez note de l’ID d’unité publicitaire et de l’ID de l’application.

    Notes

    Les valeurs d’ID d’application pour les unités d’annonces de test et les unités publicitaires UWP actives ont différents formats. Les valeurs d’ID d’application de test sont des GUID. Lorsque vous créez une unité publicitaire UWP en direct dans l’Espace partenaires, la valeur de l’ID d’application pour l’unité publicitaire correspond toujours à l’ID du Store pour votre application (un exemple de valeur d’ID du Store ressemble à 9NBLGGH4R315).

  3. Vous pouvez éventuellement activer la médiation publicitaire pour AdControl en configurant les paramètres de la section Paramètres de médiation de la page Annonces dans l’application . La médiation publicitaire vous permet d’optimiser vos revenus publicitaires et vos fonctionnalités de promotion des applications en affichant des annonces provenant de plusieurs réseaux publicitaires, y compris des publicités provenant d’autres réseaux publicitaires payants tels que Taboola et Smaato, ainsi que des publicités pour les campagnes de promotion d’applications Microsoft.

  4. Dans votre code, remplacez les valeurs d’unité publicitaire de test (applicationId et adUnitId) par les valeurs actives que vous avez générées dans l’Espace partenaires.

  5. Envoyez votre application au Windows Store à l’aide de l’Espace partenaires.

  6. Passez en revue vos rapports de performances publicitaires dans l’Espace partenaires.

Gérer les unités publicitaires pour plusieurs contrôles publicitaires dans votre application

Vous pouvez utiliser plusieurs objets AdControl dans une seule application (par exemple, chaque page de votre application peut héberger un objet AdControl différent). Dans ce scénario, nous vous recommandons d’affecter une autre unité publicitaire à chaque contrôle. L’utilisation de différentes unités publicitaires pour chaque contrôle vous permet de configurer séparément les paramètres de médiation et d’obtenir des données de création de rapports discrètes pour chaque contrôle. Cela permet également à nos services de mieux optimiser les publicités que nous proposons à votre application.

Important

Vous pouvez utiliser chaque unité publicitaire dans une seule application. Si vous utilisez une unité publicitaire dans plusieurs applications, les annonces ne seront pas diffusées pour cette unité publicitaire.