Начало работы с Vungle — iOS SDK v. 6 (Swift)

Содержание

GDPR: рекомендации по реализации

25 мая в Европейском союзе вступил в силу Общий регламент по защите данных (General Data Protection Regulation, GDPR). Разработчикам доступно два варианта соблюдения его требований.

  • Вариант 1 (рекомендуется): Издатель контролирует процесс согласия с GDPR на уровне пользователя, а затем сообщает о выборе пользователя Vungle. Для этого разработчики могут собирать данные о согласии пользователя, используя свой собственный механизм, а затем использовать API Vungle для обновления или запроса статуса согласия пользователя. Более подробная информация доступна в разделе «Рекомендованные инструкции по реализации GDPR».

  • Вариант 2: Разрешить Vungle обрабатывать требования. Vungle будет отображать диалоговое окно с запросом согласия перед воспроизведением рекламы для европейского пользователя и будет запоминать согласие или отказ пользователя для последующих показов.

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

  • Версия Vungle iOS SDK v. 6 поддерживает только iOS 8+.
  • Версия Vungle iOS SDK v. 6.x поддерживает 32- и 64-разрядные приложения.
  • Для интеграции требуется учетная запись Vungle. Если у вас еще нет учетной записи, создайте ее.
  • Последние версии SDK для iOS (начиная с 4.0.8) выпускаются в расчете на среду разработки Xcode версии 8.0. Для полной интеграции убедитесь, что используете Xcode 8.0 или более поздней версии.
  • Приведенный здесь код доступен в нашем публичном репозитории на GitHub.

 

Шаг 1. Добавление фреймворка Vungle в проект Xcode

Добавление VungleSDK.framework в проект

Добавить Vungle в проект Xcode можно двумя способами: с помощью Cocoapods или вручную.

Cocoapods

Пакет Vungle SDK доступен через Cocoapods. Чтобы добавить Vungle в проект, добавьте в podfile проекта следующую строку:

 pod "VungleSDK-iOS", "6.x"

После этого запустится процесс pod install, и свежая версия SDK для iOS будет добавлена в ваш проект. Теперь можно перейти к разделу Шаг 2. Удаление строки состояния iOS.

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

Скачать Vungle SDK v6. Если вы выполняете обновление предыдущей версии Vungle SDK, перед добавлением новой версии полностью удалите папку VungleSDK.framework.Затем найдите извлеченные файлы и перетащите папку VungleSDK.framework в раздел Frameworks в Xcode. Обязательно добавляйте папку VungleSDK.framework как группу (желтая папка), а не как вспомогательный материал (синяя папка).

Добавление других необходимых фреймворков

Vungle SDK требует привязки к проекту нескольких других «родных» фреймворков. Щелкните проект в навигаторе проектов и выберите Общие → Привязанные фреймворки и библиотеки. Многие из этих фреймворков уже подключены, поскольку они требуются по умолчанию для большинства проектов Xcode, но не забудьте добавить те, которых еще нет.

  • AdSupport.framework
  • AudioToolbox.framework
  • AVFoundation.framework
  • CFNetwork.framework
  • CoreGraphics.framework
  • CoreMedia.framework
  • Foundation.framework
  • libz.dylib или libz.tbd
  • libsqlite3.dylib или libsqlite3.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • WebKit.framework
    Примечание. установите для WebKit.framework параметр Статус в значение Необязательный, если в качестве цели развертывания выбрана версия iOS 7.

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

Добавление флага линковщика -ObjC

Нажмите проект в навигаторе проектов и выберите Параметры сборки → Линковка → Прочие флаги линковщика. Добавьте флаг -ObjC в раздел Прочие флаги линковщика.

Шаг 2. Удаление строки состояния iOS

Это необязательный шаг, но мы рекомендуем удалить строку состояния iOS, чтобы исключить помехи при показе рекламы Vungle и взаимодействии с ней. Для удаления строки состояния откройте Info.plist, добавьте ключ View controller-based status bar appearance и установите для него значение No.

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

Создание файла стыковочного заголовка

  1. Создайте новый файл Objective-C в своем проекте (Файл Создать Файл [файл Objective-C]).
  2. Xcode предложит вам создать файл стыковочного заголовка между Objective-C и Swift. Примите это предложение.
  3. Удалите новый файл Objective-C (${YOURPROJ}-Bridging-Header.m), но сохраните файл стыковочного заголовка ${YOURPROJ}-Bridging-Header.h.
  4. В файле стыковочного заголовка импортируйте Vungle SDK, добавив следующее:
    #import <VungleSDK/VungleSDK.h> 

Инициализация SDK

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

- (BOOL)startWithAppId:(nonnull NSString *)appID placements:(nonnull NSArray *)placements error:(NSError **)error;

Пример кода:

let appID = "Your_AppID_Here";
var placementIDsArray:Array<String> = ["<Your_PlacementID_1>", "<Your_PlacementID_2>", "<Your_PlacementID_3>"];

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.start(withAppId: appID, placements: placementIDsArray)
}
catch let error as NSError {
print("Error while starting VungleSDK : \(error.domain)")
return;
}

После успешной инициализации SDK вызывается следующий метод обратного вызова:

- (void)vungleSDKDidInitialize;

См. раздел Делегирование обратных вызовов в данной статье.

Проверить статус инициализации SDK можно также с помощью следующего свойства:

@property (atomic, readonly, getter=isInitialized) BOOL initialized;

После инициализации SDK, если выбрано размещение Автокэширование на панели управления Vungle, SDK автоматически кэширует рекламу для такого размещения. При использовании этой функции рекомендуем выбирать для автоматического кэширования наиболее часто просматриваемое размещение.

После успешного кэширования рекламы vungleAdPlayabilityUpdate вызывается метод с идентификатором размещения, которому присвоен статус Автокэширование. (См. раздел Проверка доступности рекламы для размещения в данной статье.)

Загрузка рекламы для размещения

Чтобы загрузить рекламу для размещений без автоматического кэширования, вызовите метод loadPlacementWithID.

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.loadPlacement(withID: <Your_PlacementID>)
}
catch let error as NSError {
print("Unable to load placement with reference ID :\(<Your_PlacementID>), Error: \(error)")

return
}

См. раздел Проверка доступности рекламы для размещения в данной статье.

Проверка доступности рекламы для размещения

После того как SDK завершит кэширование рекламы для размещения, вызывается следующий метод обратного вызова:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(nullable NSString *)placementID; 

Пример кода:

func vungleAdPlayabilityUpdate(_ isAdPlayable: Bool, placementID: String?) {
if (placementID == <Your_PlacementID>) {
self.playButtonPlacement1.enabled = isAdPlayable;
}
}

Примечание. Этот метод вызывается для размещения с автоматическим кэшированием, только когда реклама становится доступна. SDK будет продолжать запрашивать рекламу для размещения с автоматическим кэшированием. Для всех остальных размещений этот метод вызывается в случае появления ошибки «Сбой загрузки». (В этом случае (isAdPlayable возвращает NO). Проверить доступность рекламы для размещения можно также с помощью следующего свойства:

- (BOOL)isAdCachedForPlacementID:(nonnull NSString *)placementID;

Воспроизведение рекламы

Убедившись, что реклама готова к размещению, вы можете воспроизвести ее с помощью следующего метода:

- (BOOL)playAd:(UIViewController *)controller options:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error;

Пример кода:

var sdk:VungleSDK = VungleSDK.shared()
do {
try sdk.playAd(self, options: nil, placementID: kVungleTestPlacementID01)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}

Делегирование обратных вызовов

Вы можете получать обратные вызовы из SDK с помощью объекта VungleSDKDelegate. Объект делегирования предусматривает четыре метода обратного вызова, с помощью которых вы получаете уведомления о событиях SDK.

Вы можете привязывать и отвязывать объект делегирования следующим образом:

var sdk:VungleSDK = VungleSDK.shared()
// Attach
sdk.delegate = <yourDelegateInstance> as VungleSDKDelegate
// Detach
sdk.delegate = nil

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

Когда SDK готовится воспроизвести видеорекламу, вызывается следующий метод. Это подходящий момент, чтобы приостановить игру, воспроизведение звуковых эффектов, анимации и т. д.

- (void)vungleWillShowAdForPlacementID:(nullable NSString *)placementID; 

Когда SDK готовится закрыть рекламу, вызывается следующий метод. Это подходящий момент, чтобы вознаградить пользователя и возобновить игру, звуковые эффекты, анимацию и т. д.

- (void)vungleWillCloseAdWithViewInfo:(VungleViewInfo *)info placementID:(NSString *)placementID;

Когда SDK закрывает рекламу, вызывается следующий метод:

- func vungleDidCloseAd(with info: VungleViewInfo, placementID: String);

VungleViewInfo включает следующие свойства, позволяющие проверить результат воспроизведения рекламы:

@interface VungleViewInfo : NSObject //Передает логическое значение, показывающее, можно ли считать просмотр видео завершенным. @property (nonatomic, readonly) NSNumber *completedView; //Время (в секундах) просмотра видео пользователем. @property (nonatomic, readonly) NSNumber *playTime; //Значение BOOL показывающее, нажал ли пользователь кнопку скачивания. @property (nonatomic, readonly) NSNumber *didDownload; @end 

Когда SDK изменяет статус доступности рекламы, вызывается следующий метод. Логическое значение isAdPlayable обозначает новую возможность воспроизведения для конкретного идентификатора размещения placementID.

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID;

См. раздел Проверка доступности рекламы для размещения в данной статье.

После успешной инициализации SDK вызывается следующий метод:

- (void)vungleSDKDidInitialize;

Параметры настройки

Эти параметры позволяют настроить рекламу для воспроизведения.

Примечание. Рекламные объявления с вознаграждением в некоторых случаях называются рекламными объявлениями со стимулом, оба термина относятся к одному и тому же типу рекламных объявлений. В коде SDK и нашем интерфейсе Reporting API мы используем термин incentivized (со стимулом).

Ключ параметра

Значение по умолчанию / тип

Описание

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

NSString, представляющий битовую маску с ориентациями

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

VunglePlayAdOptionKeyUser

nil

NSString

Задает идентификатор пользователя. Значение передается на сервер Vungle, а затем отправляется на ваш сервер через систему обратного вызова типа сервер-сервер, если размещение предполагает вознаграждение.

VunglePlayAdOptionKeyIncentivizedAlertTitleText

nil

NSString

Заголовок предупреждения, которое появляется при преждевременном закрытии стимулированной рекламы пользователем.

VunglePlayAdOptionKeyIncentivizedAlertBodyText

«Пропустить эту рекламу? Если это сделать, вы не получите награды»

NSString

Текст предупреждения, которое появляется при преждевременном закрытии стимулированной рекламы пользователем.

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

«Закрыть»

NSString

Надпись на кнопке, закрывающей окно предупреждения, которое появляется при преждевременном закрытии стимулированной рекламы пользователем.

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

«Продолжить»

NSString

Надпись на кнопке, закрывающей окно предупреждения, которое появляется при преждевременном закрытии стимулированной рекламы пользователем.

Пример кода:

let options: NSDictionary = NSDictionary(dictionary: [VunglePlayAdOptionKeyUser: "test_user_id",
VunglePlayAdOptionKeyIncentivizedAlertBodyText: "If the video isn't completed you won't get your reward! Are you sure you want to close early?",
VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText: "Close",
VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText: "Keep Watching",
VunglePlayAdOptionKeyIncentivizedAlertTitleText: "Careful!"])
do {
try self.sdk.playAd(self, options: (options as! [AnyHashable : Any]), placementID: PlacementID)
}
catch let error as NSError {
print("Error encountered playing ad: + \(error)");
}

Параметр отключения звука

В экземпляре Vungle SDK предлагается параметр для воспроизведения рекламы без звука. Вы можете задать для свойства беззвучного воспроизведения значение true перед вызовом метода playAd().

Пример кода:

var sdk:VungleSDK = VungleSDK.shared()
sdk.muted = true

Примечание. Этот параметр применим только к рекламе стандартного типа. Параметр отключения звука для рекламы с динамическим шаблоном можно настроить на панели управления.

Отладка

Если вам нужна информация об SDK, вы можете получить ее с помощью этого свойства:

- (NSDictionary *)debugInfo;

Если вы хотите получить журналы SDK, используйте этот метод:

- (void)setLoggingEnabled:(BOOL)enable;

Протокол VungleSDKLogger

@protocol VungleSDKLogger - (void)vungleSDKLog:(NSString*)message; @end

Экземпляр-одиночка VungleSDK отправляет события журнала всем привязанным классам протокола VungleSDKLogger. Каждое событие журнала содержит значение NSString, которое также выводится на консоль (если включено ведение журналов). Подключить журналирующий объект можно следующим образом:

- (void)attachLogger:(id<VungleSDKLogger>)logger;

Как уже говорилось, важно не забывать удалять прикрепленные журналирующие объекты из Vungle SDK. Удаляются журналирующие объекты так:

- (void)detachLogger:(id<VungleSDKLogger>)logger;

Рекомендованные инструкции по реализации GDPR

Чтобы использовать API Vungle для обновления или запроса статуса согласия пользователя (как рекомендовано в Варианте 1 в разделе GDPR: рекомендации по реализации Vungle), используйте следующие функции:

//This function returns the current consent status recorded in SDK. If status is not known return 0. sdk = VungleSDK.shared() sdk?.getCurrentConsentStatus() //This function sets the current consent status recorded in the SDK sdk = VungleSDK.shared() sdk?.update(status: VungleConsentStatus) 

VungleConsentStatus представляет собой перечисление, содержащее два состояния:

  • принято (VungleConsentStatus.accepted)
  • отклонено (VungleConsentStatus.denied)
Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 0 из 0
Еще есть вопросы? Отправить запрос

Комментарии