AdControl в XAML и .NET AdControl in XAML and .NET

Начиная с 1 июня 2020 г. платформа Microsoft AD монетизацию для приложений Windows UWP будет выключена. As of June 1, 2020, the Microsoft Ad Monetization platform for Windows UWP apps will be shut down. Дополнительные сведения Learn more

В этом пошаговом руководстве рассказывается, как использовать класс AdControl для показа баннерной рекламы в приложении UWP на XAML для Windows 10, реализованном с использованием C#. This walkthrough shows how to use the AdControl class to display banner ads in a Universal Windows Platform (UWP) XAML app for Windows 10 that is implemented using C#.

Microsoft Advertising SDK также поддерживает приложения XAML, которые реализуются с использованием C++. The Microsoft Advertising SDK also supports XAML apps that are implemented using C++. Полный пример с проектом см. в разделе примеры рекламы на GitHub. For a complete sample project, see the advertising samples on GitHub.

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

• Установка Microsoft Advertising SDK с помощью Visual Studio 2015 или более поздней версии Visual Studio. Install the Microsoft Advertising SDK with Visual Studio 2015 or a later release of Visual Studio. Инструкции по установке см. в этой статье. For installation instructions, see this article.

Интеграция собственного баннера в приложение Integrate a banner ad into your app

В Visual Studio откройте свой проект либо создайте новый. In Visual Studio, open your project or create a new project.

Если вы используете существующий проект, откройте файл Package.appxmanifest в проекте и убедитесь, что возможность Интернет (клиент) выбрана. If you’re using an existing project, open the Package.appxmanifest file in your project and ensure that the Internet (Client) capability is selected. Вашему приложению эта возможность требуется для получения тестовых объявлений и настоящей рекламы. Your app needs this capability to receive test ads and live ads.

Если ваш проект направлен на работу на Любом ЦП, обновите его, чтобы он использовал результаты сборки, предназначенные для определенной архитектуры (например, x86). If your project targets Any CPU, update your project to use an architecture-specific build output (for example, x86). Если ваш проект направлен на работу на Любом ЦП, вам не удастся надлежащим образом добавить ссылку на Microsoft Advertising в приведенных ниже шагах. 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. Дополнительные сведения см. в разделе Ошибки, вызванные указанием варианта «Любой ЦП» как целевого в вашем проекте. For more information, see Reference errors caused by targeting Any CPU in your project.

Добавьте ссылку на Microsoft Advertising SDK в свой проект. Add a reference to the Microsoft Advertising SDK in your project:

1. В Обозревателе решений щелкните правой кнопкой мыши элемент Ссылки и выберите Добавить ссылку. . From the Solution Explorer window, right click References, and select Add Reference…
2. В Диспетчере ссылок разверните раздел Универсальная платформа Windows, нажмите Расширения и выберите флажок рядом с SDK Microsoft Advertising для XAML (версия 10.0). In Reference Manager, expand Universal Windows, click Extensions, and then select the check box next to Microsoft Advertising SDK for XAML (Version 10.0).
3. В диспетчере ссылок нажмите «ОК». In Reference Manager, click OK.

Измените код XAML для страницы, где вы размещаете рекламу, для включения пространства имен Microsoft.Advertising.WinRT.UI. Modify the XAML for the page where you are embedding advertising to include the Microsoft.Advertising.WinRT.UI namespace. Например, в образце приложения по умолчанию, созданного Visual Studio (с названием MyAdFundedWindows10AppXAML в этом приложении), страницей XAML является MainPage.xaml. For example, in the default sample app generated by Visual Studio (named, in this app, MyAdFundedWindows10AppXAML), the XAML page is MainPage.XAML.

Раздел Page файла MainPage.xaml, созданного Visual Studio, содержит следующий код. The Page section of the MainPage.xaml file generated by Visual Studio has the following code.

Добавьте ссылку на пространство имен Microsoft.Advertising.WinRT.UI, чтобы раздел Page файла MainPage.xaml содержал следующий код. Add the namespace reference Microsoft.Advertising.WinRT.UI so the Page section of the MainPage.xaml file has the following code.

В раздел под тегом Grid добавьте код для AdControl. In the Grid tag, add the code for the AdControl. Назначьте свойствам ApplicationId и AdUnitId значения тестовой группы объявлений. Assign the AdUnitId and ApplicationId properties to the test ad unit values. Также настройте высоту и ширину элемента управления, чтобы он был одним из поддерживаемых размеров рекламы для баннеров. Also adjust the Height and Width of the control so it is one of the supported ad sizes for banner ads.

Каждый элемент AdControl имеет соответствующую группу объявлений, используемую нашими службами для передачи рекламы этому элементу управления, и каждая группа объявлений состоит из идентификатора группы объявлений и идентификатора приложения. Every AdControl has a corresponding ad unit that is used by our services to serve ads to the control, and every ad unit consists of an ad unit ID and application ID. На этих этапах вы задаете тестовые значения идентификатора группы объявлений и идентификатора приложения для своего элемента управления. In these steps, you assign test ad unit ID and application ID values to your control. Эти тестовые значения можно использовать только в тестовой версии приложения. These test values can only be used in a test version of your app. Перед публикацией приложения в хранилище эти тестовые значения необходимо заменить на значения в реальном времени из центра партнеров. Before you publish your app to the Store, you must replace these test values with live values from Partner Center.

Полностью код раздела под тегом Grid выглядит следующим образом. The complete Grid tag looks like this code.

Полный код для файла MainPage.xaml должен выглядеть так. The complete code for the MainPage.xaml file should look like this.

Скомпилируйте и запустите приложение, чтобы увидеть его с объявлением. Compile and run the app to see it with an ad.

Выпуск приложения с реальной рекламой Release your app with live ads

Убедитесь, что использование вами рекламных баннеров в своем приложении соответствует нашим рекомендациям для рекламных баннеров. Make sure your use of banner ads in your app follows our guidelines for banner ads.

В центре партнеров перейдите на страницу рекламных объявлений в приложении и Создайте модуль AD. In Partner Center, go to the In-app ads page and create an ad unit. В качестве типа группы объявлений укажите Баннер. For the ad unit type, specify Banner. Запомните идентификатор группы объявлений и идентификатор приложения. Make note of both the ad unit ID and the application ID.

Значения идентификатора приложения для тестовых рекламных блоков и реальных рекламных блоков UWP имеют разные форматы. The application ID values for test ad units and live UWP ad units have different formats. Тестовые значения идентификатора приложения представляют собой элементы GUID. Test application ID values are GUIDs. При создании активной единицы AD UWP в центре партнеров значение идентификатора приложения для единицы AD всегда совпадает с ИДЕНТИФИКАТОРом магазина для вашего приложения (пример значения идентификатора магазина выглядит как 9NBLGGH4R315). When you create a live UWP ad unit in Partner Center, the application ID value for the ad unit always matches the Store ID for your app (an example Store ID value looks like 9NBLGGH4R315).

Вы можете при необходимости включить рекламный посредник для AdControl, настроив параметры в разделе Параметры посредника на странице Реклама в приложении. You can optionally enable ad mediation for the AdControl by configuring the settings in the Mediation settings section on the In-app ads page. С помощью рекламного посредника можно максимально увеличить выручку от рекламы и возможности ее продвижения, отображая рекламу от нескольких рекламных сетей, в том числе других платных рекламных сетей, например Taboola и Smaato, и рекламных объявлений для кампаний по продвижению приложения Microsoft. Ad mediation enables you to maximize your ad revenue and app promotion capabilities by displaying ads from multiple ad networks, including ads from other paid ad networks such as Taboola and Smaato and ads for Microsoft app promotion campaigns.

В коде замените значения тестовых единиц AD (applicationId и адунитид) на значения в реальном времени, созданные в центре партнеров. In your code, replace the test ad unit values (ApplicationId and AdUnitId) with the live values you generated in Partner Center.

Отправьте приложение в магазин с помощью центра партнеров. Submit your app to the Store using Partner Center.

Управление группами объявлений для нескольких элементов управления рекламой в приложении Manage ad units for multiple ad controls in your app

Вы можете использовать несколько объектов AdControl в одном приложении (например, каждая страница в вашем приложении может содержать свой объект AdControl). You can use multiple AdControl objects in a single app (for example, each page in your app might host a different AdControl object). В этом случае рекомендуется назначить каждому элементу управления свою группу объявлений. In this scenario, we recommend that you assign a different ad unit to each control. Использование различных групп объявлений для каждого элемента управления позволяет по отдельности настраивать параметры посредника и получать раздельные данные отчетности для каждого элемента управления. Using different ad units for each control enables you to separately configure the mediation settings and get discrete reporting data for each control. Это также позволяет нашим службам лучше оптимизировать рекламные объявления, которые мы передаем вашему приложению. This also enables our services to better optimize the ads we serve to your app.

Одну группу объявлений можно использовать только в одном приложении. You can use each ad unit in only one app. Если использовать одну группу объявлений в нескольких приложениях, объявления для этой группы объявлений предоставляться не будут. If you use an ad unit in more than one app, ads will not be served for that ad unit.

Установить пакет Microsoft Advertising SDK Install the Microsoft Advertising SDK

Начиная с 1 июня 2020 г. платформа Microsoft AD монетизацию для приложений Windows UWP будет выключена. As of June 1, 2020, the Microsoft Ad Monetization platform for Windows UWP apps will be shut down. Дополнительные сведения Learn more

Для отображения рекламы в приложениях UWP для Windows 10 установите Microsoft Advertising SDK. To display ads in your UWP apps for Windows 10, install the Microsoft Advertising SDK. Этот пакет SDK является расширением Visual Studio 2015 и последующих версий. This SDK is an extension to Visual Studio 2015 and later versions.

Если вы разрабатываете приложение UWP на JavaScript или HTML и установили пакет SDK для Windows 10 версии 10.0.14393 (годовщина) или более позднюю версию, необходимо также установить библиотеку WinJS . If you are developing a JavaScript/HTML UWP app and you have installed Windows 10 SDK version 10.0.14393 (Anniversary Update) or later, you must also install the WinJS library. Эта библиотека ранее включалась в предыдущие версии Windows 10 SDK, но, начиная с Windows 10 SDK версии 10.0.14393 (юбилейное обновление), ее необходимо устанавливать отдельно. This library used to be included in previous versions of the Windows 10 SDK, but starting with the Windows 10 SDK version 10.0.14393 (Anniversary Update) this library must be installed separately.

Установка с помощью MSI Install via MSI

Установка Microsoft Advertising SDK с помощью установщика MSI. To install the Microsoft Advertising SDK via the MSI installer:

Закройте все экземпляры Visual Studio. Close all instances of Visual Studio.

Если вы ранее устанавливали какую-либо из предыдущих версий пакетов Microsoft Advertising SDK, Universal Ad Client SDK, расширения Ad Mediator или Microsoft Store Engagement and Monetization SDK, теперь необходимо удалить эти версии пакетов SDK. If you previously installed any previous version of the Microsoft Advertising SDK, Universal Ad Client SDK, Ad Mediator extension, or Microsoft Store Engagement and Monetization SDK, uninstall these SDK versions now. Другой вариант: откройте окно командной строки и выполните эти команды для удаления всех более ранних версий пакетов рекламных SDK, которые могли быть установлены вместе с Visual Studio, но, возможно, не отображаются в списке установленных программ на компьютере: Optionally, open a Command Prompt window and run these commands to clean out any older advertising SDK versions that may have been installed with Visual Studio, but which may not appear in the list of installed programs on your computer:

Скачайте и установите пакет Microsoft Advertising SDK. Download and install the Microsoft Advertising SDK. Установка может занять несколько минут. It may take a few minutes to install. Обязательно дождитесь завершения процесса. Be sure and wait until the process has finished.

Перезапустите Visual Studio. Restart Visual Studio.

Если у вас есть существующий проект, который ссылается на рекламные библиотеки из какой-либо более ранней версии пакетов Microsoft Advertising SDK, Universal Ad Client SDK или Microsoft Store Engagement and Monetization SDK, рекомендуется открыть этот проект в Visual Studio, очистить и заново собрать проект (в Обозревателе решений щелкните правой кнопкой мыши по узлу проекта и выберите пункт Очистить, затем снова щелкните правой кнопкой мыши по узлу проекта и выберите Пересобрать). If you have an existing project that references advertising libraries from any earlier version of the Microsoft Advertising SDK, Universal Ad Client SDK, or Microsoft Store Engagement and Monetization SDK, we recommend that you open your project in Visual Studio and clean and rebuild your project (in Solution Explorer, right-click your project node and choose Clean, and then right-click your project node again and choose Rebuild).

В противном случае, если вы используете пакет Microsoft Advertising SDK в первый раз в своем проекте, теперь вы готовы добавить ссылку на Microsoft Advertising SDK. Otherwise, if you are using the Microsoft Advertising SDK for the first time in your project, you are now ready to add a reference to the Microsoft Advertising SDK.

Установка с помощью NuGet Install via NuGet

Установка библиотек Microsoft Advertising SDK в конкретный проект UWP с помощью NuGet. To install the Microsoft Advertising SDK in a specific UWP project via NuGet:

Закройте все экземпляры Visual Studio. Close all instances of Visual Studio.

Если вы ранее устанавливали какую-либо из предыдущих версий пакетов Microsoft Advertising SDK, Universal Ad Client SDK, расширения Ad Mediator или Microsoft Store Engagement and Monetization SDK, теперь необходимо удалить эти версии пакетов SDK. If you previously installed any previous version of the Microsoft Advertising SDK, Universal Ad Client SDK, Ad Mediator extension, or Microsoft Store Engagement and Monetization SDK, uninstall these SDK versions now. Другой вариант: откройте окно командной строки и выполните эти команды для удаления всех более ранних версий пакетов рекламных SDK, которые могли быть установлены вместе с Visual Studio, но, возможно, не отображаются в списке установленных программ на компьютере: Optionally, open a Command Prompt window and run these commands to clean out any older advertising SDK versions that may have been installed with Visual Studio, but which may not appear in the list of installed programs on your computer:

Запустите Visual Studio и откройте проект, в котором вы хотите использовать библиотеки Microsoft Advertising SDK. Start Visual Studio and open the project in which you want to use the Microsoft Advertising SDK.

Если ваш проект уже содержит ссылки на библиотеки из предыдущей установки пакета SDK с помощью MSI, удалите эти ссылки из проекта. If your project already includes library references from an earlier MSI installation of the SDK, remove these references from your project. Рядом с этими ссылками будут расположены предупреждающие значки, поскольку библиотеки, на которые они ссылаются, были удалены ранее. These references will have warning icons next to them because the libraries they reference were removed in the previous steps.

В Visual Studio щелкните Проект и выберите параметр Управление пакетами NuGet. In Visual Studio, click Project and Manage NuGet Packages.

В поле поиска введите Microsoft.Advertising.XAML (для проектов на XAML) или Microsoft.Advertising.JS (для проектов на JavaScript и HTML) и установите соответствующий пакет. In the search box, type Microsoft.Advertising.XAML (for a XAML project) or Microsoft.Advertising.JS (for a JavaScript/HTML project) and install the corresponding package. Когда установка пакета завершится, сохраните решение. When the package is done installing, save your solution.

Если в окне Вывод содержится ошибка Install-Package, указывающая, что заданный путь слишком длинный, вам может потребоваться настроить NuGet, чтобы извлечь пакеты в альтернативное расположение с более коротким путем, чем расположение по умолчанию. If the Output window reports an Install-Package error that indicates the specified path is too long, you may need to configure NuGet to extract packages to an alternate location with a shorter path than the default location. Для этого добавьте значение repositoryPath в файл nuget.config на компьютере и задайте ему более короткий путь к папке, куда можно извлечь пакеты NuGet. To do this, add the repositoryPath value to a nuget.config file on your computer and assign it to a short folder path where NuGet packages can be extracted. Дополнительные сведения см. в этой статье в документации NuGet. For more information, see this article in the NuGet documentation. Кроме того можно попробовать переместить проект Visual Studio в другую папку с более коротким путем. Alternatively, you can try moving your Visual Studio project to an alternate folder with a shorter path.

Закройте решение и снова откройте его. Close your solution and then reopen it.

Если проект уже содержит ссылки на библиотеки из более ранней версии Microsoft Advertising SDK, которая была установлена с помощью NuGet, и вы обновили свой проект до более нового выпуска SDK, рекомендуется очистить и пересобрать проект (в Обозревателе решений щелкните правой кнопкой мыши по узлу проекта и выберите пункт Очистить, затем снова щелкните правой кнопкой мыши по узлу проекта и выберите Пересобрать). If your project already references libraries from an earlier version of the Microsoft Advertising SDK that was installed via NuGet and you have updated your project to a newer release of the SDK, we recommend that you clean and rebuild your project (in Solution Explorer, right-click your project node and choose Clean, and then right-click your project node again and choose Rebuild).

В противном случае, если вы используете пакет SDK в первый раз в своем проекте, теперь вы готовы добавить ссылку на Microsoft Advertising SDK. Otherwise, if you are using the SDK for the first time in your project, you are now ready to add a reference to the Microsoft Advertising SDK.

Добавление ссылки на Microsoft Advertising SDK Add a reference to the Microsoft Advertising SDK

После установки пакета Microsoft Advertising SDK следуйте этим инструкциям, чтобы создать ссылку на SDK в своем проекте и иметь возможность использовать рекламные API-интерфейсы. After you install the Microsoft Advertising SDK, follow these instructions to reference the SDK in your project so you can use the advertising APIs.

Откройте проект в Visual Studio. Open your project in Visual Studio.

Если ваш проект направлен на работу на Любом ЦП, обновите его, чтобы он использовал результаты сборки, предназначенные для определенной архитектуры (например, x86). If your project targets Any CPU, update your project to use an architecture-specific build output (for example, x86). Если ваш проект направлен на работу на Любом ЦП, вам не удастся надлежащим образом добавить ссылку на Microsoft Advertising SDK в приведенных ниже шагах. If your project targets Any CPU, you will not be able to successfully add a reference to the Microsoft Advertising SDK in the following steps. Дополнительные сведения см. в разделе Ошибки, вызванные указанием варианта «Любой ЦП» как целевого в вашем проекте. For more information, see Reference errors caused by targeting Any CPU in your project.

В Обозревателе решений щелкните правой кнопкой мыши пункт Ссылки и выберите Добавить ссылку. In Solution Explorer, right click References and select Add Reference…

В диспетчере ссылок разверните Universal Windows, нажмите Расширения и затем установите флажок рядом с Microsoft Advertising SDK для XAML (для приложений, использующих XAML) или Microsoft Advertising SDK для JavaScript (для приложений, созданных с помощью JavaScript и HTML). In Reference Manager, expand Universal Windows, click Extensions, and then select the check box next to Microsoft Advertising SDK for XAML (for XAML apps) or Microsoft Advertising SDK for JavaScript (for apps built using JavaScript and HTML).

В диспетчере ссылок нажмите «ОК». In Reference Manager, click OK.

Руководства, в которых рассказывается, как приступить к использованию API рекламы, см. в следующих статьях. For walkthroughs that show how to get started using the advertising APIs, see the following articles:

Общие сведения о пакетах платформы в Microsoft Advertising SDK Understanding framework packages in the Microsoft Advertising SDK

Библиотека Microsoft.Advertising.dll в пакете SDK для Microsoft Advertising (для приложений UWP) настраивается как пакет платформы. The Microsoft.Advertising.dll library in the Microsoft Advertising SDK (for UWP apps) is configured as a framework package. Эта библиотека содержит рекламные API-интерфейсы в пространствах имен Microsoft.Advertising и Microsoft.Advertising.WinRT.UI. This library contains the advertising APIs in the Microsoft.Advertising and Microsoft.Advertising.WinRT.UI namespaces.

Поскольку библиотека представляет собой пакет платформы, это означает, что после установки пользователем версии вашего приложения, которое применяет эту библиотеку, библиотека будет автоматически обновляться на устройстве пользователя через Центр обновления Windows, когда мы опубликуем новую версию библиотеки с исправлениями и улучшенной производительностью. Because this library is a framework package, this means that after a user installs a version of your app that uses this library, this library is automatically updated on their device through Windows Update whenever we publish a new version of the library with fixes and performance improvements. Это позволяет гарантировать, что ваши клиенты всегда будут иметь последнюю доступную версию библиотеки на своих устройствах. This helps to ensure that your customers always have the latest available version of the library installed on their devices.

Если мы выпустим новую версию SDK с новыми API или функциями в этой библиотеке, вам придется установить последнюю версию пакета SDK, чтобы использовать их. If we release a new version of the SDK that introduces new APIs or features in this library, you will need to install the latest version of the SDK to use those features. В этом случае вам также понадобится опубликовать обновленное приложение в Магазине. In this scenario, you would also need to publish your updated app to the Store.