Интеграция SDK Vungle для Windows

David Kim

13/01/2021 20:14

С помощью этого руководства вы можете быстро интегрировать наш SDK в свое приложение и начать зарабатывать. Примеры кода в этом руководстве приведены в C#, но мы предлагаем файлы примера приложения в C#, C++, Visual Basic и DirectX+XAML в нашем хранилище GitHub.

Перед началом работы

Требования

Для интеграции требуется аккаунт Vungle, поэтому, если вы еще это не сделали, создайте аккаунт Vungle и создайте в своем аккаунте приложение Windows Universal Windows. Инструкции по установке мест размещения на панели управления Vungle приведены в разделе Добавление приложений и мест размещения нашей статьи Использование панели управления издателя.
Если вы разрабатываете для Windows 8.1, то должны использовать Visual Studio 2015, поскольку Microsoft больше не поддерживает Windows 8.1 для Visual Studio 2017.
Кнопка Назад поддерживается на мобильных устройствах, но не на ПК (клавиатуре). Это влияет на работу приложения и его взаимодействие с пользователями в версиях для универсальной платформы Windows.
На Панели управления переключите свое приложение в режим Активно, если реклама не отображается в режиме Тест.

Скачать SDK

Если вы предпочитаете интеграцию вручную, вы можете скачать SDK Vungle для Windows здесь: https://publisher.vungle.com/sdk/sdks/windows.

Для справки: пример приложения

При интеграции пользуйтесь предоставленным нами примером приложения: https://github.com/Vungle/Windows-SDK/tree/master.

Шаг 1. Интеграция SDK Vungle

Существует два способа добавления Vungle в проект Visual Studio: с помощью NuGet (рекомендуемый) или интеграция вручную.

Вариант 1. Интеграция с NuGet (рекомендуемый)

В Visual Studio нажмите правой кнопкой мыши на имени вашего проекта в Solution Explorer и выберите Управление пакетами NuGet.
Нажмите Просмотр, введите «Vungle» и выберите Vungle SDK.
Нажмите Установить.

Вариант 2. Интеграция вручную

Скачайте пакет Vungle Windows SDK из панели управления Vungle.
Извлеките архив.
В Visual Studio создайте новый проект Universal Windows с помощью соответствующего шаблона для своего приложения и языка программирования.
Добавьте ссылку для своего проекта в скачанный файл SDK Vungle Windows.
В SDK Vungle есть два VungleSDK.windmd файла: один для разработки в Windows 10 и один для разработки в Windows 8.1. Используйте правильный SDK из разархивированной папки: Win10 или Win81.
Убедитесь, что в вашем проекте есть internetClient возможность в package.appxmanifest файле. Возможность «Интернет (клиент)» включена по умолчанию при создании нового проекта. Это можно проверить в Visual Studio или посредством редактирования вручную.
- Для проверки наличия возможности internetClient в Visual Studio:
  1. В Visual Studio дважды нажмите appxmanifest в Solution Explorer.
  2. Выберите Возможности.
  3. Убедитесь, что выбран параметр Интернет (клиент).
- Для проверки наличия возможности internetClient с помощью редактирования вручную откройте файл package.appxmanifeset и добавьте internetClient в раздел Capabilities:
```
<Capabilities>
    ...
    <Capability Name="internetClient" />
    ...
</Capabilities>
```

Шаг 2. Импорт Пространства имен `VungleSDK`

Импортируйте пространство имен VungleSDK следующим образом:

с помощью SDK Vungle;

Шаг 3. Получение Экземпляра `VungleAd`

В SDK Vungle версии 6.3.0 и выше экземпляр VungleAd принимает только один параметр: ваш идентификатор приложения Vungle.

VungleAd sdkInstance;
string appID = “app_id”;
sdkInstance = AdFactory.GetInstance(appID);

В примере выше appId следует заменить вашим идентификатором приложения Vungle. Мы рекомендуем выполнить эти шаги инициализации сразу же после того, как ваше приложение закончит загружать критические компоненты, чтобы начать оптимизацию кэша.

В SDK Vungle версии 6.2.0 и ниже экземпляр VungleAd принимает два параметра: строку для вашего идентификатора приложения Vungle и массив строк для индентификаторов мест размещения. Вы можете использовать только те индентификаторы мест размещения, которые вы добавили при получении экземпляра.

sdkInstance = AdFactory.GetInstance(appID, placementList);

Шаг 4. Добавление кода

Создание и регистрация обработчиков событий

SDK Windows инициирует несколько событий, которые можно обрабатывать программно. Вы можете использовать эти обработчики событий для управления возможностями своего приложения, такими как приостановка или возобновление фоновой музыки.

Замечание о потоке пользовательского интерфейса

Прослушиватели событий выполняются в фоновом потоке, поэтому любые взаимодействия или обновления пользовательского интерфейса, вызванные прослушивателем событий, перед выполнением должны быть переданы в основной поток пользовательского интерфейса. Вот один из способов, позволяющих это сделать:

await this.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
  new DispatchedHandler(() =>
  {
    // This block will be executed in the UI thread
  }
);

Диагностика

Этот обработчик событий вызывается, когда SDK хочет распечатать журналы диагностики.

Пример кода:

//Register event handler
sdkInstance.Diagnostic          += SdkInstance_Diagnostic;

...

// 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) { }

`OnAdPlayableChanged`

Создайте обработчик для события OnAdPlayableChanged. Этот обработчик событий вызывается, когда изменяется состояние доступности рекламы. Дождитесь выполнения этим обработчиком действия, при котором реклама становится доступной после загрузки рекламы для размещения. Определить, какое место размещения инициировало событие, можно, проверив e.Placement.

// Event handler for OnAdPlayableChanged event
private async void SdkInstance_OnAdPlayableChanged(object sender, AdPlayableEventArgs e)
{
  if (e.AdPlayable == true)
  {
    // e.Placement - placement ID in string
    // Run asynchronously on the UI thread
    await CoreApplication.MainView.Dispatcher.RunAsync(CoreDispatcherPriority.Normal,
      new DispatchedHandler(() => methodToRun(e.Placement)));
  }
}

Зарегистрируйте этот обработчик событий на событие OnAdPlayableChanged.

sdkInstance.OnAdPlayableChanged += SdkInstance_OnAdPlayableChanged;

`OnInitCompleted`

Этот обработчик событий вызывается сразу после завершения инициализации SDK. Вы можете проверить наличие рекламы, загруженной из предыдущей сессии, или загрузить рекламу для размещения.

Пример кода:

//Register event handler
sdkInstance.OnInitCompleted     += SdkInstance_OnInitCompleted;

...

// 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)));
}

`OnAdStart`

Этот обработчик событий вызывается перед воспроизведением рекламы. Вы можете выполнять такие действия, как приостановление фоновой музыки.

Пример кода:

//Register event handler
sdkInstance.OnAdStart           += SdkInstance_OnAdStart;

...

// 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`

Этот обработчик событий вызывается, когда пользователь закрывает конечную карту и управление передается назад вашему приложению. Если значение IsCompletedView или CallToActionClicked действительно, пользователь просмотрел рекламу или нажал кнопку загрузки в рекламе. В этом случае, если это была реклама с вознаграждением, пользователь должен получить вознаграждение. Вы можете выполнять такие действия, как возобновление функций приложения.

Пример кода:

//Register event handlers
sdkInstance.OnAdEnd             += SdkInstance_OnAdEnd;

...

// 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);
}

Интеграция форматов рекламы

Выполните интеграцию SDK для каждого формата рекламы, которую вы планируете отображать в своем приложении. Смотрите наши инструкции для каждого формата рекламы:

Расширенная настройка рекламы

Следуйте инструкциям в нашей статье Расширенные настройки для точной настройки интеграции вашего приложения с дополнительными возможностями, такими как внедрение GDPR, CCPA и многими другими настройками.

Перед началом работы

Требования

Скачать SDK

Для справки: пример приложения

Шаг 1. Интеграция SDK Vungle

Вариант 1. Интеграция с NuGet (рекомендуемый)

Вариант 2. Интеграция вручную

Шаг 2. Импорт Пространства имен VungleSDK

Шаг 3. Получение Экземпляра VungleAd

Шаг 4. Добавление кода

Создание и регистрация обработчиков событий

Замечание о потоке пользовательского интерфейса

Диагностика

OnAdPlayableChanged

OnInitCompleted

OnAdStart

OnAdEnd

Интеграция форматов рекламы

Расширенная настройка рекламы

Questions?

Шаг 2. Импорт Пространства имен `VungleSDK`

Шаг 3. Получение Экземпляра `VungleAd`

`OnAdPlayableChanged`

`OnInitCompleted`

`OnAdStart`

`OnAdEnd`