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

Содержание

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

  • Версия Vungle iOS SDK v. 5 поддерживает iOS 8+.
  • Версия Vungle iOS SDK v. 5 была испытана с версией iOS 11 beta/GM Seed.
  • Версия Vungle iOS SDK v. 5 поддерживает 32- и 64-разрядные приложения.
  • Для интеграции требуется учетная запись Vungle. Если у вас еще нет учетной записи, создайте ее.
  • Наш пакет iOS SDK поддерживает Xcode 8.0 и 9.0. Для полной интеграции убедитесь, что используете Xcode 8.0 или более позднюю версию.

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

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

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

Cocoapods

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

 pod "VungleSDK-iOS", "5.3.0"

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

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

Скачать Vungle SDK v5. Если вы выполняете обновление предыдущей версии Vungle 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
  • 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. Добавление кода

Инициализация 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);
}

Объявления Flex Feed

Теперь Vungle SDK v.5.3 поддерживает рекламные объявления Flex Feed. Это первый формат рекламных объявлений, который не требует полного экрана; вместо этого издатель определяет точные размеры и расположение контейнера объявления в своем приложении. Эти контейнеры рекламных объявлений могут быть в представлениях коллекций или в представлениях таблиц.

Загрузка рекламного объявления Flex Feed

Загрузка рекламного объявления Flex Feed выполняется так же, как и загрузка полноэкранного объявления; однако для поддержки функций Flex Feed необходимо настроить размещение. Свяжитесь со своим менеджером по работе с клиентами Vungle, чтобы активировать размещение Flex Feed.

Отображение рекламного объявления Flex Feed

Отображение рекламных объявлений Flex Feed отличается от отображения полноэкранных объявлений. При использовании рекламных объявлений Flex Feed необходимо сначала создать контейнер для объявления. Это контейнер UIView. Указанный контейнер UIView можно разместить в любом месте экрана. Рекламное объявление будет масштабироваться до любого размера контейнера, но имейте в виду, что очень низкое разрешение сделает объявление менее четким. Затем необходимо вызвать функцию addAdViewToView для установления связи контейнера с объявлением Flex Feed.

Обзор функций


/**
 * Pass in an UIView which acts as a container for the ad experience. This view container may be placed in random positions.
 * @param publisherView container view in which an ad will be displayed
 * @param options A reference to an instance of NSDictionary with customized ad playback options
 * @param placementID The placement defined on the Vungle dashboard
 * @param error An optional double reference to an NSError. In case this method returns `NO` it will be non-nil
 * @return YES/NO in case of success/error while presenting an AdUnit
 */
- (BOOL)addAdViewToView:(UIView *)publisherView withOptions:(nullable NSDictionary *)options placementID:(nullable NSString *)placementID error:( NSError *__autoreleasing _Nullable *_Nullable)error;

Пример кода:


NSError *error;
NSDictionary *options = @{};
VungleSDK* sdk = [VungleSDK sharedSDK];
[sdk addAdViewToView:_FlexFeedViewArea withOptions:options placementID: error:&error];
if (error) 
{
        NSLog(@"Error encountered while playing an ad: %@", error);
}

Закрытие рекламного объявления Flex Feed

Из-за особенности объявлений Flex Feed пользователь может остановить просмотр видео, не закрывая объявление. Поэтому пакету SDK необходимо дать команду закрыть объявление, когда оно больше не отображается на экране. Для этого необходимо вызвать функцию finishedDisplayingAd .

Обзор функций


/**
 * This method must be called when the publisher is confident that they are finished displaying the ad unit.
 * This signals to the SDK that a new ad may be fetched or a different ad may be displayed. This will
 * be called in conjunction with `addViewToView:containedInViewController:withOptions:placementID:error:`
 */
- (void)finishedDisplayingAd;

Пример кода:


//Ad is no longer on screen
VungleSDK* sdk = [VungleSDK sharedSDK];
[sdk finishedDisplayingAd];

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

Вы можете получать обратные вызовы из 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;

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

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

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

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

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

Описание

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
Еще есть вопросы? Отправить запрос

Комментарии