Начало работы с пакетом Vungle SDK 5.1+ для iOS

Содержание

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

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

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

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

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

Cocoapods

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

 pod "VungleSDK-iOS", "5.1.0"

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

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

Скачайте Vungle SDK v5.1.0. Если вы выполняете обновление предыдущей версии Vungle SDK, перед добавлением нового SDK полностью удалите папку VungleSDK.framework.

Если вы выполняете обновление предыдущей версии Vungle SDK, перед добавлением нового SDK полностью удалите папку VungleSDK.framework.

Найдите извлеченные файлы и перетащите папку VungleSDK.framework в раздел Frameworks в Xcode. Обязательно добавляйте папку 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

Убедитесь также, что фреймворк 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. Добавление кода

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

Примечание.​ Для каждого приложения создается размещение по умолчанию. На данном шаге инициализации необходимо указать идентификатор размещения, независимо от того, планируете ли вы использовать функции размещения. Если вы создаете несколько размещений, укажите все идентификаторы.

Инициализируйте SDK при запуске приложения, чтобы осталось достаточно времени для кэширования рекламы (для размещения с автоматическим кэшированием). Для инициализации SDK вам потребуются идентификатор приложения и идентификаторы всех размещений (активных и неактивных), которые будут использоваться в приложении. Эти идентификаторы можно найти на панели управления Vungle (см. раздел Настройка размещений на панели управления Vungle).

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

Пример кода:

#import <VungleSDK/VungleSDK.h>
...
NSError* error;
NSString* appID = @"Your_AppID_Here"; NSArray* placementIDsArray = @[@"<Your_PlacementID_1>", @"<Your_PlacementID_2>", @"<Your_PlacementID_3>"]; VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk startWithAppId:appID placements:placementIDsArray error:&error];

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

- (void)vungleSDKDidInitialize;

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

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

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

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

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

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

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

- (BOOL)loadPlacementWithID:(NSString *)placementID error:(NSError **)error;

Пример кода:

NSError* error;
VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk loadPlacementWithID:"<Your_PlacementID>" error:&error];

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

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

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

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

Пример кода:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID {
    if([placementID isEqualToString:@"<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;

Пример кода:

VungleSDK* sdk = [VungleSDK sharedSDK];
NSError *error;
[self.sdk playAd:self options:nil placementID:@"<Your_PlacementID_1>" error:&error];
if (error) {
    NSLog(@"Error encountered playing ad: %@", error);
}

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

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

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

// Attach
[[VungleSDK sharedSDK] setDelegate:yourDelegateInstance];
// Отвязывание
[[VungleSDK sharedSDK] setDelegate:nil];

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

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

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

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


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

VungleViewInfo includes the following properties for you to check a result of ad play:

@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;

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

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

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

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

Описание

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

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

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

VunglePlayAdOptionKeyUser

nil

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertTitleText

nil

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertBodyText

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

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

«Закрыть»

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

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

NSString

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

Пример кода:

NSDictionary *options = @{VunglePlayAdOptionKeyOrientations: @(UIInterfaceOrientationMaskLandscape),
                          VunglePlayAdOptionKeyUser: @"userGameID",
                          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!"};

// Передача параметров, воспроизведение рекламы
NSError *error;
[self.sdk playAd:self options:options placementID: error:&error];

if (error) {
    NSLog(@"Error encountered playing ad: %@", error);
}

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

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

Пример кода:

VungleSDK* sdk = [VungleSDK sharedSDK];
self.sdk.muted = true;

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

Отладка

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

- (NSDictionary *)debugInfo;

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

- (void)setLoggingEnabled:(BOOL)enable;

Протокол VungleSDKLogger

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

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

[sdk attachLogger:yourLoggerInstance];

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

[sdk detachLogger:yourLoggerInstance];

assetLoader Protocol

@protocol VungleAssetLoader
/**
 * должен вернуть действительное значение типа NSData с raw-данными изображения для указанного пути либо nil. */
- (NSData*)vungleLoadAsset:(NSString*)path;

/**
 * должен вернуть действительное UIImage для указанного пути либо nil.
 */
- (UIImage*)vungleLoadImage:(NSString*)path;
@end
Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 0 из 0
Еще есть вопросы? Отправить запрос

Комментарии