Воспользуйтесь этим руководством, чтобы быстро интегрировать наш SDK в свое приложение и начать монетизировать его.
Примеры кода в этом руководстве приводятся на языке C#, однако мы предоставляем файлы примеров приложений sample на C#, C++, Visual Basic и DirectX+XAML из нашего репозитория GitHub.
Содержание
- GDPR: рекомендации по реализации
- Перед началом работы
- Скачайте пакет SDK и добавьте VungleSDK в свой проект
- Импортируйте пространство имен VungleSDK
- Получите экземпляр VungleAd
- Создание и регистрация обработчика событий
- Загрузка рекламы для размещения
- Воспроизведение рекламы для размещения
- Параметры настройки
- Создание обработчиков событий
- Показ рекламы Native Flex
GDPR: рекомендации по реализации
25 мая в Европейском союзе вступил в силу Общий регламент по защите данных (General Data Protection Regulation, GDPR). Разработчикам доступно два варианта соблюдения его требований.
-
Вариант 1 (рекомендуется): Издатель контролирует процесс согласия с GDPR на уровне пользователя, а затем сообщает о выборе пользователя Vungle. Для этого разработчики могут собирать данные о согласии пользователя, используя свой собственный механизм, а затем использовать API Vungle для обновления или запроса статуса согласия пользователя. Более подробная информация доступна в разделе «Рекомендованные инструкции по реализации GDPR».
- Вариант 2: Разрешить Vungle обрабатывать требования. Vungle будет отображать диалоговое окно с запросом согласия перед воспроизведением рекламы для европейского пользователя и будет запоминать согласие или отказ пользователя для последующих показов.
Перед началом работы
- Это руководство предназначено для Vungle Windows SDK 5.3.2 и более поздних версий. Руководство по интеграции Vungle Windows SDK версии 1.3.16 и более ранних приведено здесь: Начало работы с Vungle — Windows SDK v. 1.0 — v.1.3.16 .
- Для интеграции требуется учетная запись Vungle. Если у вас ее нет, создайте ее.
- Если вы этого еще не сделали, перейдите на панель управления и добавьте приложение в свою учетную запись. Чтобы узнать, как настраиваются размещения на панели управления Vungle, ознакомьтесь со статьей Setting Up and Reporting on Placements (Настройка размещений и отчеты по ним).
- При разработке продуктов для Windows 8.1 and Windows Phone 8.1 следует использовать Visual Studio 2015, поскольку в Visual Studio 2017 поддержка этих версий прекращена.
- Кнопка Back (Назад) поддерживается на мобильных устройствах, но не на ПК (для его клавиатуры). Это может приводить к различиям в поведении и взаимодействии с пользователем для сборок UWP.
- Если в режиме тестирования не было возвращено ни одного объявления, переключите свое приложение в активный режим.
Скачайте пакет SDK и добавьте VungleSDK в свой проект
Добавить Vungle в проект Visual Studio можно двумя способами: с помощью NuGet или вручную.
Вариант 1. Интеграция NuGet
- В Visual Studio, нажмите правой кнопкой мыши Проект и выберите Управление пакетами NuGet.
- Нажмите Просмотр, введите «Vungle», выберите Vungle SDK и нажмите Установить.
Вариант 2. Интеграция вручную
- Скачайте пакет Vungle Windows SDK из панели управления Vungle.
- Извлеките архив.
- В Visual Studio создайте новый проект, используя соответствующий шаблон для вашего приложения и языка программирования.
- Добавьте ссылку на ваш проект в загруженный файл SDK Vungle для Windows.
В Vungle SDK есть два файла VungleSDK.windmd: для разработки на Windows 10 или 8.1. Используйте подходящий SDK из извлеченного каталога: Win10 или Win81.
Возможности InternetClient
Убедитесь, что ваш проект имеет возможности internetClient в файле package.appxmanifest.
Visual Studio
- Дважды щелкните
appxmanifestв обозревателе решений. - Выберите Возможности
- Убедитесь, что выбран параметр Интернет (клиент).
Редактирование вручную
Откройте файл package.appxmanifeset и добавьте internetClient в раздел Возможности.
<Capabilities>
...
<Capability Name="internetClient" />
...
</Capabilities> Импортируйте пространство имен VungleSDK
using VungleSDK;Получите экземпляр VungleAd
Экземпляр VungleAd принимает два параметра: строку для идентификатора вашего приложения Vungle и массив строк для идентификаторов размещений. Вы можете использовать только те идентификаторы, которые уже были включены вами при получении данного экземпляра. Если вы не включили одно размещение с автоматическим кэшированием, пакет SDK автоматически назначит одно из размещений без автоматического кэширования в качестве размещения с автоматическим кэшированием.
VungleAd sdkInstance; string appID = “app_id”; string[] placementArray = new string[] { “placement_id_1”, “placement_id_2”, “placement_id_3” };
sdkInstance = AdFactory.GetInstance(appID, placementArray); В примере выше замените app_id на идентификатор вашего приложения Vungle и placement_id_# на идентификаторы размещений, которые будут использоваться в вашем проекте. Чтобы ускорить запуск автоматического кэширования, мы рекомендуем вам выполнять эти шаги инициализации до тех пор, пока ваше приложение не завершит загрузку критически важных компонентов.
Создание и регистрация обработчика событий
Создайте обработчик событий для события OnAdPlayableChanged. Этот обработчик событий вызывается, когда изменяется статус доступности рекламы. Вы можете указать, какое размещение активирует событие, выбрав e.Placement.
// Обработчик событий для события OnAdPlayableChanged private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e) { // e.Placement – идентификатор размещения в строке // Запустить асинхронно в потоке пользовательского интерфейса await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => methodToRun(e.Placement))); } Зарегистрируйте этот обработчик событий для события OnAdPlayableChanged.
sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged; Загрузка рекламы для размещения
Для размещений, не являющихся размещениями с автоматическим кэшированием, необходимо сначала вызвать LoadAd, чтобы предоставить достаточно времени для скачивания рекламных ресурсов, а затем подождать вызова OnAdPlayableChanged:
sdkInstance.LoadAd(“placement_id”); Примечание. Размещение с автоматическим кэшированием будет пытаться скачать новый рекламный ресурс сразу же после вызова PlayAdAsync, поэтому вызывать LoadAd не требуется.
Пример кода:
private void OnLevelStart(Object sender, RoutedEventArgs e) { sdkInstance.LoadAd(“placement_id”); } Воспроизведение рекламы
Запустите рекламу в конфигурации по умолчанию:
sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”); Пример кода:
private async void OnLevelComplete(Object sender, RoutedEventArgs e) { await sdkInstance.PlayAdAsync(new AdConfig(), “placement_id”); } Вы можете дополнительно настроить воспроизводимые объявления, предоставив параметры объекту AdConfig.
Пример кода:
private async void PlayCustomizedAd(Object sender, RoutedEventArgs e) { AdConfig adConfig = new AdConfig(); adConfig.Orientation = DisplayOrientations.Portrait; adConfig.SoundEnabled = false; await sdkInstance.PlayAdAsync(adConfig, placement2); } Параметры настройки
В экземпляре объекта AdConfig доступны следующие свойства:
Примечание. Рекламные объявления с вознаграждением в некоторых случаях называются рекламными объявлениями со стимулом, оба термина относятся к одному и тому же типу рекламных объявлений. В коде SDK и нашем интерфейсе Reporting API мы используем термин incentivized (со стимулом).
|
Параметры |
Значение по умолчанию/ |
Описание |
|
|
AutoRotate DisplayOrientations |
Примечание. Этот параметр применим только к рекламе для мобильных устройств. |
|
|
true Логич. |
Задает начальное состояние звука для рекламного объявления. Если указано true (по умолчанию), используются громкость и настройки звука устройства. Если указано false, видео начинает воспроизводиться с отключенным звуком, но пользователь может это изменить. |
|
|
false Логич. |
Если указано true, пользователь может незамедлительно закрыть объявление с помощью кнопки «Назад». При значении false (по умолчанию) пользователь не может использовать кнопку «Назад» для выхода из объявления, пока не покажется кнопка «Закрыть» на экране. Примечание. Этот параметр применим только к рекламе для мобильных устройств. |
|
|
null строка |
Передает уникальный идентификатор пользователя в ваше приложение, подтверждающий при проверке, что этот пользователь должен быть вознагражден за просмотр стимулированной рекламы, когда для проверки используется обратный вызов типа сервер-сервер. Примечание. Этот параметр применим только к размещениям с вознаграждением. |
|
|
«Close this ad?» (Закрыть это объявление?) строка |
Задает заголовок диалога подтверждения при пропуске стимулированной рекламы. Примечание. Этот параметр применим только к размещениям с вознаграждением. |
|
|
«Пропустить эту рекламу? Чтобы претендовать на вознаграждение, вы должны завершить просмотр.» строка |
Задает текст диалога подтверждения при пропуске стимулированной рекламы. Примечание. Этот параметр применим только к размещениям с вознаграждением. |
|
|
«Закрыть»
строка |
Задает текст кнопки 'cancel' диалога подтверждения при пропуске стимулированной рекламы. Примечание. Этот параметр применим только к размещениям с вознаграждением. |
|
|
«Продолжить» строка |
Задает текст кнопки 'keep watching' диалога подтверждения при пропуске стимулированной рекламы. Примечание. Этот параметр неприменим, если реклама не является стимулированной. |
|
|
- |
УСТАРЕЛО Вы можете задать конфигурацию с вознаграждением на уровне размещений из панели управления. См. статью Setting Up and Reporting on Placements (Настройка размещений и отчеты по ним). |
Примечание. Параметры SoundEnabled и стимулированных диалоговых окон рекламы с динамическим шаблоном и Flex View доступны для настройки на панели управления. Программная конфигурация будет применяться только к устаревшей рекламе.
Отображение кнопки «Закрыть»
Чтобы управлять возможностью пользователя закрывать объявление, используйте параметры принудительного просмотра в расширенных настройках вашего приложения на панели управления Vungle.
Рекомендованные инструкции по реализации GDPR
// To set the user’s consent status as opted in: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentAccepted); // To set the user’s consent status as opted out: sdkInstance.UpdateConsentStatus(VungleConsentStatus.VungleConsentDenied); // To find out what the user’s current consent status is: // This will return null if the GDPR Consent status has not been set // Otherwise, it will return VungleConsentStatus.VungleConsentAccepted or // VungleConsentStatus.VungleConsentDenied UpdateConsentStatus? currentStatus = sdkInstance.GetCurrentConsentStatus(); Создание обработчиков событий
Пакет Windows SDK формирует несколько событий, которыми можно управлять программно. Вы можете использовать эти обработчики событий для управления возможностями своего приложения, такими как приостановка или возобновление фоновой музыки.
Замечание о потоке пользовательского интерфейса
Прослушиватели событий выполняются в фоновом потоке, поэтому любые взаимодействия или обновления пользовательского интерфейса, вызванные прослушивателем событий, должны быть перед выполнением переданы в основной поток пользовательского интерфейса. Вот один из способов, позволяющих это сделать:
await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
new DispatchedHandler(() =>
{ // This block will be executed in the UI thread
} ); Обработчики событий VungleAd
|
Обработчики событий |
Описание |
|
|
Вызывается сразу же после завершения инициализации SDK. Вы можете проверить, имеется ли реклама, загруженная из предыдущего сеанса, или же загрузить рекламу для размещений. |
|
|
Уведомляет об изменении доступности объявления для данного размещения. Ожидает, пока этот обработчик событий не выполнит соответствующее действие, когда реклама становится доступна после ее загрузки для размещения. |
|
|
Вызывается перед воспроизведением объявления. Вы можете выполнять такие действия, как, например, приостановка фоновой музыки. |
|
|
Вызывается, когда пользователь закрывает последний кадр и управление возвращается в приложение. Если значением |
|
|
Вызывается, когда для SDK требуется распечатка журналов диагностики. |
Пример кода:
//Register event handlers sdkInstance.OnInitCompleted += SdkInstance_OnInitCompleted; sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged; sdkInstance.OnAdStart += SdkInstance_OnAdStart; sdkInstance.OnAdEnd += SdkInstance_OnAdEnd; sdkInstance.Diagnostic += SdkInstance_Diagnostic; ... // OnInitCompleted // e.Initialized - true if initialization succeeded, false if failed // e.ErrorMessage - reason for failure when e.Initialized is false private async void SdkInstance_OnInitCompleted(object sender, ConfigEventArgs e) { var placementsInfo = "OnInitCompleted: " + e.Initialized; // Initilization was success if (e.Initialized == true) { // Print out list of placements for (var i = 0; i < e.Placements.Length; i++) { placementsInfo += "\n\tPlacement" + (i + 1) + ": " + e.Placements[i].ReferenceId; if (e.Placements[i].IsAutoCached == true) placementsInfo += " (Auto-Cached)"; } } // Initilization failed else { placementsInfo += "\n\t" + e.ErrorMessage; } System.Diagnostics.Debug.WriteLine(placementsInfo); await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => NotifyInitialization(e.Initialized))); } // OnAdPlayableAdPlayable // e.AdPlayable - true if an ad is available to play, false otherwise // e.Placement - placement ID in string private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e) { System.Diagnostics.Debug.WriteLine("OnAdPlayable(" + e.Placement + ") - " + e.AdPlayable); await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal, new DispatchedHandler(() => NotifyWatcher(e.AdPlayable, e.Placement))); } // OnAdStart // e.Id - Vungle app ID in string // e.Placement - placement ID in string private void SdkInstance_OnAdStart(object sender, AdEventArgs e) { System.Diagnostics.Debug.WriteLine("OnAdStart(" + e.Id + "): " + e.Placement); } // OnAdEnd // e.Id - Vungle app ID in string // e.Placement - placement ID in string // e.IsCompletedView- true when 80% or more of the video was watched // e.CallToActionClicked - true when the user has clicked download button on end card // e.WatchedDuration - DEPRECATED private void SdkInstance_OnAdEnd(object sender, AdEndEventArgs e) { System.Diagnostics.Debug.WriteLine("OnVideoEnd(" + e.Id + "): " + "\n\tPlacement: " + e.Placement + "\n\tIsCompletedView: " + e.IsCompletedView + "\n\tCallToActionClicked: " + e.CallToActionClicked + "\n\tWatchedDuration: " + e.WatchedDuration); } // Event handler called when SDK wants to print diagnostic logs private void SdkInstance_Diagnostic(object sender, DiagnosticLogEvent e) { System.Diagnostics.Debug.WriteLine("Diagnostic - "
+ e.Level + " "
+ e.Type + " "
+ e.Exception + " "
+ e.Message); } // DEPRECATED - Use SdkInstance_OnAdEnd() instead private void SdkInstance_OnVideoView(object sender, AdViewEventArgs e) { } Показ рекламы Native Flex
Vungle Windows SDK 5.1.0+ поддерживает нашу новую рекламную функцию Native Flex. VungleAdControl добавляет видеорекламу в нативных форматах, передавая настроенный пакет в Vungle SDK с помощью свойства AdConfig.AdContainer и управляя содержимым Container.Content хост-приложения.
Требования к рекламе Native Flex
- Windows SDK 5.1.0+
- UWP для Windows 10
Для конфигурации показа рекламы Native Flex проконсультируйтесь со своим менеджером по работе с клиентами или напишите по адресу: tech-support@vungle.com.
Настройка пользовательского интерфейса для рекламы Native Flex – XAML
Для VungleAdControl следует указать идентификатор приложения Vungle, все идентификаторы размещения, используемые в приложении, и идентификатор размещения для конкретного размещения просмотра или подачи Native Flex. Вы также можете назначить метод UserId, который используется здесь для размещений с вознаграждением.
Пример кода:
<Grid
<UI:VungleAdControl x:Name="vungleEmbedded"
Height="200"
Width="300"
AppID="vungle_app_id"
Placements="placement_id_1,placement_id_2,native_flex_id"
Placement = "native_flex_id"
UserId="vungle_test_user">
<TextBlock x:Name="Vungle Native Flex Ad"/>
</UI:VungleAdControl>
</Grid>Загрузка рекламы Native Flex
Загрузка рекламы с помощью размещения Native Flex аналогична загрузке полноэкранной рекламы.
Пример кода:
sdkInstance.LoadAd(“native_flex_id”); Показ рекламы Native Flex
Показ рекламы с помощью размещения Native Flex подобен показу полноэкранных реклам, однако настройку следует конфигурировать в файле .xaml или на панели управления, включая запуск рекламы с выключенным звуком.
Пример кода:
await vungleEmbedded.PlayAdAsync();Закрытие рекламы Native Flex
В силу характера рекламы Native Flex пользователь может прекратить просмотр видео без закрытия объявления. Поэтому вы должны указать, что SDK следует закрыть рекламу, если она больше не отображается на экране. С этой целью мы разработали два метода закрытия рекламы Native Flex:
- Используйте
CloseFlexViewAd(String placementId)для немедленного закрытия рекламы с указанным идентификатором размещения.
- Используйте
SetFlexViewCloseTimeInSec(String placementId, int seconds)для закрытия данного размещения по истечении заданного количества секунд.
Обработчики событий для рекламы Native Flex
Для идеального взаимодействия с пользователем рекомендуется зарегистрировать отдельные обработчики событий для управления различным поведением полноэкранных и нативных рекламных роликов.
Пример кода:
vungleEmbedded.OnAdStart += (sender, arg) => { ... } vungleEmbedded.OnAdEnd += (sender, arg) => { ... } await vungleEmbedded.PlayAdAsync();