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

Содержание

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

  • Версия Vungle iOS SDK v. 5.x поддерживает только iOS 8+.
  • Версия Vungle iOS SDK v. 5.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", "5.x"

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

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

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

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

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

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

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

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

Щелкните проект в навигаторе проектов​ и выберите Build Settings → Linking → Other Linker Flags (Параметры сборки → Линковка → Прочие флаги линковщика)​. Добавьте флаг -ObjC​ в раздел Other Linker Flags​ (Прочие флаги линковщика).

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

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

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

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

  1. Создайте новый файл Objective-C в своем проекте (File  New  File [Objective-C File] ("Файл" → "Создать" → "Файл [файл 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 (см. раздел Настройка размещений на панели управления 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 автоматически кэширует рекламное объявление для размещения, которому присвоен статус Auto Cached (Автокэширование) на панели управления Vungle. Рекомендуем выбирать для автоматического кэширования самое часто просматриваемое размещение.

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

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

Чтобы загрузить рекламу для размещений без автоматического кэширования, вызовите метод 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 будет продолжать запрашивать рекламу для размещения с автоматическим кэшированием. Для всех остальных размещений этот метод вызывается в случае появления ошибки Load Failed (Сбой загрузки). (В этом случае (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;

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;

Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 0 из 0
Еще есть вопросы? Отправить запрос

Комментарии