1. Vungle RU
  2. Monetization
  3. Рекомендации по интеграции SDK для iOS

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

Avatar
John Mai
Подписаться

Содержание

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 была испытана с версией iOS 11 beta/GM Seed.
  • Версия Vungle iOS SDK v. 6 поддерживает 32- и 64-разрядные приложения.
  • Для интеграции требуется учетная запись Vungle. Если у вас еще нет учетной записи, создайте ее.
  • Наш SDK для iOS поддерживает Xcode 9.0 и более поздних версий.

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

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

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

Cocoapods

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

 pod "VungleSDK-iOS", "6.2.0"

После этого запустится процесс 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
  • libz.dylib или libz.tbd
  • MediaPlayer.framework
  • QuartzCore.framework
  • StoreKit.framework
  • SystemConfiguration.framework


Примечание: Vungle SDK V.6 не поддерживает iOS 7. Если в качестве вашей цели развертывания выбрана iOS 7, используйте Vungle iOS SDK v.4.1 или более ранние версии и включите эти фреймворки:

  • UIKit.framework
  • WebKit.framework
  • Foundation.framework

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

Добавление флага линковщика -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.

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

Пример кода:

#import <VungleSDK/VungleSDK.h>
...
NSError* error;
NSString* appID = @"Your_AppID_Here"; VungleSDK* sdk = [VungleSDK sharedSDK]; [sdk startWithAppId:appID error:&error];

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

- (void)vungleSDKDidInitialize;

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

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

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

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

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

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

Чтобы загрузить рекламу для размещений без автоматического кэширования, вызовите метод 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 error:(nullable NSError *)error; 

Пример кода:

- (void)vungleAdPlayabilityUpdate:(BOOL)isAdPlayable placementID:(NSString *)placementID error:(nullable NSError *)error {
    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. Эта функция работает только с рекламой Flex Feed и Flex View. Обратите внимание, что эта функция не принимает размещение; она просто закрывает любое нативное рекламное объявление, которое воспроизводится в данный момент.

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

/** * 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;

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

- (void)vungleDidCloseAdWithViewInfo:(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:(nullable NSString *)placementID error:(nullable NSError *)error;

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

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

- (void)vungleSDKDidInitialize;

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

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

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

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

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

Описание

VunglePlayAdOptionKeyOrientations

autorotate

UIInterfaceOrientationMaskAll

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

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

VunglePlayAdOptionKeyUser

nil

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertTitleText

nil

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertBodyText

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

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertCloseButtonText

«Закрыть»

NSString

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

VunglePlayAdOptionKeyIncentivizedAlertContinueButtonText

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

NSString

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

Int

Используйте этот параметр, чтобы реклама Flex View закрывалась автоматически через указанное количество секунд.
Эта функция работает только с рекламой Flex View.
VunglePlayAdOptionKeyOrdinal

Int

Если вы получаете отчеты о порядковых данных из Vungle, используйте это поле, чтобы передать порядковый номер посредника. Это целое число, указывающее порядок, в котором это рекламное объявление было показано в игровом сеансе (например, если два объявления уже были показаны в этом сеансе, и это рекламное объявление из Vungle было показано третьим, передайте «3»). Подробнее об порядковых данных см. здесь.

 

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!"}; // Pass in dict of options, play ad 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;

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

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

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

// This function sets the consent status that will be recorded in Vungle SDK. Accepted values: 'VungleConsentAccepted' or 'VungleConsentDenied'.
// To set the user's consent status to opted in:
 [[VungleSDK sharedSDK] updateConsentStatus:VungleConsentAccepted];

// To set the user's consent status to opted out:
 [[VungleSDK sharedSDK] updateConsentStatus:VungleConsentDenied];

// To find out what the user's current consent status is: 
// (Check against enum values: 'VungleConsentAccepted' or 'VungleConsentDenied'.) [[VungleSDK sharedSDK] getCurrentConsentStatus];

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

  • VungleConsentAccepted
  • VungleConsentDenied

SDK также имеет начальное состояние «неизвестно» (null), которое предлагает пользователю согласиться или отказаться от сбора данных о пользователе. Обратите внимание, что этот запрос выполняется только для IP-адресов, расположенных в Европе.

Отладка

Если вам нужна информация об 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
Powered by Creativity Driven by Performance Sign Up Here

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Отправить запрос
Была ли эта статья полезной?