AdControl в HTML 5 и JavaScript

  • Статья

Предупреждение

С 1 июня 2020 г. платформа монетизации Microsoft Ad для приложений UWP для Windows будет отключена. Подробнее

В этом пошаговом руководстве показано, как использовать класс AdControl для отображения рекламных баннеров в универсальная платформа Windows (UWP) javaScript/HTML-приложении для Windows 10 и Windows 11.

Полный пример с проектом, демонстрирующим способы добавления баннерной рекламы в приложение на JavaScript и HTML, см. в разделе примеров рекламы на GitHub.

Предварительные требования

Примечание

Если вы установили пакет SDK для Windows 10 версии 10.0.14393 (юбилейное обновление) или более позднюю версию пакета WINDOWS SDK, необходимо также установить библиотеку WinJS. Эта библиотека ранее включалась в предыдущие версии Windows SDK для Windows 10, но, начиная с Windows 10 SDK версии 10.0.14393 (юбилейное обновление), ее необходимо устанавливать отдельно.

Интеграция собственного баннера в приложение

  1. В Visual Studio откройте свой проект либо создайте новый.

    Примечание

    Если вы используете существующий проект, откройте файл Package.appxmanifest в проекте и убедитесь, что возможность Интернет (клиент) выбрана. Вашему приложению эта возможность требуется для получения тестовых объявлений и настоящей рекламы.

  2. Если ваш проект направлен на работу на Любом ЦП, обновите его, чтобы он использовал результаты сборки, предназначенные для определенной архитектуры (например, x86). Если ваш проект направлен на работу на Любом ЦП, вам не удастся надлежащим образом добавить ссылку на Microsoft Advertising в приведенных ниже шагах. Дополнительные сведения см. в разделе Ошибки, вызванные указанием варианта "Любой ЦП" как целевого в вашем проекте.

  3. Добавьте ссылку на Microsoft Advertising SDK в свой проект.

    1. В Обозревателе решений щелкните правой кнопкой мыши элемент Ссылки и выберите Добавить ссылку....
    2. В Диспетчере ссылок разверните раздел Универсальная платформа Windows, нажмите Расширения и выберите флажок рядом с Microsoft Advertising SDK для JavaScript (версия 10.0).
    3. В диспетчере ссылок нажмите "ОК".

  4. Откройте файл index.html (или другой html-файл, если это необходимо для вашего проекта).

  5. <В разделе head> после ссылок на JavaScript проекта default.css и main.js добавьте ссылку на ad.js.

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

    Примечание

    Эта строка должна быть помещена <в раздел head> после включения main.js. В противном случае при сборке проекта возникнет ошибка.

  6. Измените <раздел body> в файле default.html (или другой HTML-файл, соответствующий вашему проекту), чтобы включить div для AdControl. Назначьте свойствам applicationId и adUnitId в разделе AdControlзначения тестовой группы объявлений. Кроме того, измените высоту и ширину элемента управления, чтобы эти параметры соответствовали одному из поддерживаемых размеров объявлений для баннерной рекламы.

    Примечание

    Каждый элемент AdControl имеет соответствующую группу объявлений, используемую нашими службами для передачи рекламы этому элементу управления, и каждая группа объявлений состоит из идентификатора группы объявлений и идентификатора приложения. На этих этапах вы задаете тестовые значения идентификатора группы объявлений и идентификатора приложения для своего элемента управления. Эти тестовые значения можно использовать только в тестовой версии приложения. Перед публикацией приложения в Магазине необходимо заменить эти тестовые значения динамическими значениями из Центра партнеров.

    <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. Скомпилируйте и запустите приложение, чтобы увидеть его с объявлением.

В следующем примере показан полный файл index.html для простого приложения.

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

Создание элемента AdControl программными средствами в JavaScript

Предыдущие действия показывают, как объявить AdControl в разметке HTML. Также можно программным способом создавать AdControl на JavaScript. В этом примере предполагается, что вы используете существующий элемент div в html-коде с идентификатором 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;

В этом примере предполагается, что вы уже объявили методы обработчика событий с названиями myAdError, myAdRefreshed и myAdEngagedChanged.

Если вы используете этот код и не видите рекламу, попробуйте задать атрибут position:relative в элементе div, содержащем AdControl. Это переопределяет параметр по умолчанию для IFrame. Объявления будут отображаться правильно, если их отображение не отключено значением этого атрибута. Обратите внимание, что новые рекламные блоки, могут быть недоступны до 30 минут.

Примечание

Значения applicationId и adUnitId, приведенные в данном примере, являются значениями тестового режима. Перед отправкой приложения необходимо заменить эти значения динамическими значениями из Центра партнеров.

Выпуск приложения с реальной рекламой

  1. Убедитесь, что использование вами рекламных баннеров в своем приложении соответствует нашим рекомендациям для рекламных баннеров.

  2. В Центре партнеров перейдите на страницу объявлений в приложении и создайте рекламное подразделение. В качестве типа группы объявлений укажите Баннер. Запомните идентификатор группы объявлений и идентификатор приложения.

    Примечание

    Значения идентификатора приложения для тестовых рекламных блоков и реальных рекламных блоков UWP имеют разные форматы. Тестовые значения идентификатора приложения представляют собой элементы GUID. При создании динамической рекламной группы UWP в Центре партнеров значение идентификатора приложения для рекламного блока всегда совпадает с идентификатором Магазина для вашего приложения (пример значения идентификатора Магазина выглядит как 9NBLGGH4R315).

  3. Вы можете при необходимости включить рекламный посредник для AdControl, настроив параметры в разделе Параметры посредника на странице Реклама в приложении. С помощью рекламного посредника можно максимально увеличить выручку от рекламы и возможности ее продвижения, отображая рекламу от нескольких рекламных сетей, в том числе других платных рекламных сетей, например Taboola и Smaato, и рекламных объявлений для кампаний по продвижению приложения Microsoft.

  4. В коде замените значения тестового рекламного блока (applicationId и adUnitId) динамическими значениями, созданными в Центре партнеров.

  5. Отправьте приложение в Магазин с помощью Центра партнеров.

  6. Просмотрите отчеты о результативности рекламы в Центре партнеров.

Управление группами объявлений для нескольких элементов управления рекламой в приложении

Вы можете использовать несколько объектов AdControl в одном приложении (например, каждая страница в вашем приложении может содержать свой объект AdControl). В этом случае рекомендуется назначить каждому элементу управления свою группу объявлений. Использование различных групп объявлений для каждого элемента управления позволяет по отдельности настраивать параметры посредника и получать раздельные данные отчетности для каждого элемента управления. Это также позволяет нашим службам лучше оптимизировать рекламные объявления, которые мы передаем вашему приложению.

Важно!

Одну группу объявлений можно использовать только в одном приложении. Если использовать одну группу объявлений в нескольких приложениях, объявления для этой группы объявлений предоставляться не будут.