„AdControl“ in HTML 5 und JavaScript

  • Artikel

Warnung

Ab dem 1. Juni 2020 wird die Microsoft Ad Monetization-Plattform für Windows UWP-Apps abgeschaltet. Weitere Informationen

In dieser exemplarischen Vorgehensweise wird gezeigt, wie Sie die AdControl-Klasse verwenden, um Banneranzeigen in einer JavaScript-/HTML-App für Windows 10 und Windows 11 (Universelle Windows-Plattform) anzuzeigen.

Ein vollständiges Beispielprojekt, das veranschaulicht, wie Banneranzeigen zu einer JavaScript/HTML-App hinzugefügt werden, finden Sie in den Werbebeispielen auf GitHub.

Voraussetzungen

Hinweis

Wenn Sie die Windows 10 SDK-Version 10.0.14393 (Anniversary Update) oder eine höhere Version des Windows SDK installiert haben, müssen Sie auch die WinJS-Bibliothek installieren. Diese Bibliothek wurde verwendet, um in früheren Versionen des Windows SDK für Windows 10 enthalten zu sein, aber ab der Windows 10 SDK-Version 10.0.14393 (Anniversary Update) muss diese Bibliothek separat installiert werden.

Integrieren einer Banneranzeige in Ihre App

  1. Öffnen Sie in Visual Studio Ihr Projekt, oder erstellen Sie ein neues Projekt.

    Hinweis

    Wenn Sie ein vorhandenes Projekt verwenden, öffnen Sie die Datei "Package.appxmanifest" in Ihrem Projekt, und stellen Sie sicher, dass die Internetfunktion (Client) ausgewählt ist. Ihre App benötigt diese Funktion, um Testanzeigen und Liveanzeigen zu erhalten.

  2. Wenn Ihr Projekt auf eine beliebige CPU ausgerichtet ist, aktualisieren Sie Ihr Projekt so, dass eine architekturspezifische Buildausgabe verwendet wird (z. B. x86). Wenn Ihr Projekt auf "Any CPU" ausgerichtet ist, können Sie in den folgenden Schritten keinen Verweis auf die Microsoft Advertising-Bibliothek hinzufügen. Weitere Informationen finden Sie unter Referenzfehler, die durch die Ausrichtung von Any CPU in Ihrem Projekt verursacht werden.

  3. Fügen Sie einen Verweis auf die Microsoft Advertising-SDK in Ihrem Projekt hinzu:

    1. Klicken Sie im fenster Projektmappen-Explorer mit der rechten Maustaste auf "Verweise", und wählen Sie "Verweis hinzufügen" aus...
    2. Erweitern Sie im Verweis-Manager universelles Windows, klicken Sie auf Erweiterungen, und aktivieren Sie dann das Kontrollkästchen neben Microsoft Advertising-SDK für JavaScript (Version 10.0).
    3. Klicken Sie im Verweis-Manager auf "OK".

  4. Öffnen Sie die index.html Datei (oder eine andere HTML-Datei entsprechend für Ihr Projekt).

  5. Fügen Sie im <Abschnitt "Head> " nach den JavaScript-Verweisen des Projekts default.css und main.js den Verweis auf ad.js hinzu.

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

    Hinweis

    Diese Zeile muss nach dem <Einschließen von main.js im Kopfbereich> platziert werden. Andernfalls tritt beim Erstellen des Projekts ein Fehler auf.

  6. Ändern Sie den Textabschnitt> in der default.html-Datei (oder einer anderen HTML-Datei entsprechend für Ihr Projekt), um das div-Element für adControl einzuschließen.< Weisen Sie die ApplicationId - und adUnitId-Eigenschaften von AdControl den Werten der Testanzeigeeinheit zu. Passen Sie außerdem die Höhe und Breite an, sodass das Steuerelement eine der unterstützten Anzeigengrößen für Banneranzeigen ist.

    Hinweis

    Jedes AdControl verfügt über eine entsprechende Anzeigeneinheit , die von unseren Diensten verwendet wird, um Anzeigen an das Steuerelement zu stellen, und jede Anzeigeneinheit besteht aus einer Anzeigeneinheits-ID und Anwendungs-ID. In diesen Schritten weisen Sie Ihrem Steuerelement Testanzeigeneinheits-ID und Anwendungs-ID-Werte zu. Diese Testwerte können nur in einer Testversion Ihrer App verwendet werden. Bevor Sie Ihre App im Store veröffentlichen, müssen Sie diese Testwerte durch Livewerte aus Partner Center ersetzen.

    <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. Kompilieren Sie die App, und führen Sie sie aus, um sie mit einer Anzeige anzuzeigen.

Das folgende Beispiel zeigt die vollständige index.html für eine einfache App.

<!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>

Programmgesteuertes Erstellen eines AdControl in JavaScript

In den vorherigen Schritten wird gezeigt, wie Sie ein AdControl-Objekt in Ihrem HTML-Markup deklarieren. Alternativ können Sie programmgesteuert ein AdControl mit JavaScript erstellen. In diesem Beispiel wird davon ausgegangen, dass Sie ein vorhandenes div-Element in Ihrem HTML-Code mit der ID "myAd" verwenden.

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;

In diesem Beispiel wird davon ausgegangen, dass Sie bereits Ereignishandlermethoden namens "myAdError", "myAdRefreshed" und "myAdEngagedChanged" deklariert haben.

Wenn Sie diesen Code verwenden und keine Anzeigen sehen, können Sie versuchen, ein Attribut von position:relative in das div-Element einzufügen, das das AdControl enthält. Dadurch wird die Standardeinstellung des IFrame außer Kraft setzen. Anzeigen werden korrekt angezeigt, es sei denn, sie werden aufgrund des Werts dieses Attributs nicht angezeigt. Beachten Sie, dass neue Anzeigeneinheiten möglicherweise bis zu 30 Minuten nicht verfügbar sind.

Hinweis

Die in diesem Beispiel gezeigten werte applicationId und adUnitId sind Testmoduswerte. Sie müssen diese Werte durch Livewerte aus partner Center ersetzen, bevor Sie Ihre App zur Übermittlung übermitteln.

Veröffentlichen Ihrer App mit Liveanzeigen

  1. Stellen Sie sicher, dass Ihre Verwendung von Banneranzeigen in Ihrer App unsere Richtlinien für Banneranzeigen befolgt.

  2. Wechseln Sie im Partner Center zur Seite "In-App-Anzeigen ", und erstellen Sie eine Anzeigeneinheit. Geben Sie für den Anzeigeneinheitstyp Banner an. Notieren Sie sich sowohl die Anzeigeneinheits-ID als auch die Anwendungs-ID.

    Hinweis

    Die Anwendungs-ID-Werte für Testanzeigeeinheiten und Live-UWP-Anzeigeneinheiten weisen unterschiedliche Formate auf. Testanwendungs-ID-Werte sind GUIDs. Wenn Sie eine Live-UWP-Anzeigeneinheit im Partner Center erstellen, entspricht der Anwendungs-ID-Wert für die Anzeigeneinheit immer der Store-ID für Ihre App (ein Beispiel für den Store-ID-Wert sieht wie 9NBLGGH4R315 aus).

  3. Sie können optional die Anzeigenvermittlung für adControl aktivieren, indem Sie die Einstellungen im Abschnitt "Vermittlungseinstellungen" auf der Seite "In-App-Anzeigen" konfigurieren. Mit der Anzeigenvermittlung können Sie Ihre Werbeeinnahmen und App-Werbungsfunktionen maximieren, indem Sie Anzeigen aus mehreren Anzeigennetzwerken anzeigen, einschließlich Anzeigen aus anderen kostenpflichtigen Anzeigennetzwerken wie Taboola und Smaato und Anzeigen für Microsoft-App-Werbekampagnen.

  4. Ersetzen Sie in Ihrem Code die Testanzeigeneinheitswerte (applicationId und adUnitId) durch die Livewerte, die Sie im Partner Center generiert haben.

  5. Übermitteln Sie Ihre App über das Partner Center an den Store.

  6. Überprüfen Sie Ihre Anzeigenleistungsberichte im Partner Center.

Verwalten von Anzeigeneinheiten für mehrere Anzeigensteuerelemente in Ihrer App

Sie können mehrere AdControl-Objekte in einer einzelnen App verwenden (beispielsweise kann jede Seite in Ihrer App ein anderes AdControl-Objekt hosten). In diesem Szenario wird empfohlen, jedem Steuerelement eine andere Anzeigeneinheit zuzuweisen. Durch die Verwendung unterschiedlicher Anzeigeneinheiten für jedes Steuerelement können Sie die Vermittlungseinstellungen separat konfigurieren und diskrete Berichtsdaten für jedes Steuerelement abrufen. Dies ermöglicht es unseren Diensten auch, die Werbung, die wir ihrer App anbieten, besser zu optimieren.

Wichtig

Sie können jede Anzeigeneinheit nur in einer App verwenden. Wenn Sie eine Anzeigeneinheit in mehr als einer App verwenden, werden Anzeigen für diese Anzeigeneinheit nicht bereitgestellt.