myTarget SDK предоставляет возможность показывать рекламу в своем приложении, используя собственные визуальные компоненты. SDK загружает данные и предоставляет приложению модель рекламного объявления с определенными свойствами для заполнения визуального компонента, а также методы для подсчета показов и обработки кликов. SDK также предоставляет готовый настраиваемый визуальный компонент, который вы можете использовать в вашем приложении, вместо создания собственных.
Нативный баннер не поддерживает MTRGMediaAdView и поэтому не может отображать медиа-контент (видео, карточки, большую картинку).
Инициализация
Для показа нативных баннеров в вашем приложении необходимо создать экземпляр класса MTRGNativeBannerAd. Для создания экземпляра MTRGNativeBannerAd необходимо указать ваш slotId.
@interface YourViewController : UIViewController
@end
@implementation YourViewController
{
MTRGNativeBannerAd *_ad;
}
- (void)initAd
{
// Включение режима отладки
// [MTRGManager setDebugMode:YES];
// Создаем экземпляр MTRGNativeAd
_ad = [MTRGNativeBannerAd nativeBannerAdWithSlotId:YOUR_SLOT_ID];
}
Загрузка рекламных объявлений
Для получения уведомлений (таких как успешная загрузка данных или ошибка загрузки, клик по рекламному объявлению) необходимо установить созданному экземпляру MTRGNativeBannerAd делегат, реализующий протокол MTRGNativeBannerAdDelegate, после чего можно запустить загрузку данных.
@interface YourViewController : UIViewController <MTRGNativeBannerAdDelegate>
@end
@implementation YourViewController
{
MTRGNativePromoAd *_ad;
}
- (void)initAd
{
// Создаем экземпляр MTRGNativeAd
_ad = [MTRGNativeBannerAd nativeBannerAdWithSlotId:YOUR_SLOT_ID];
// Устанавливаем делегат
_ad.delegate = self;
// Запускаем загрузку данных
[_ad load];
}
- (void)onLoadWithNativeBanner:(MTRGNativeBanner *)banner nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onLoadFailedWithError:(NSError *)error nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onAdShowWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onAdClickWithClickedView:(UIView *)clickedView nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onShowModalWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onDismissModalWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
- (void)onLeaveApplicationWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
}
Политика загрузки медиа файлов
Политика загрузки задает поведение SDK, если ему не удалось загрузить медиа файлы для рекламы. Политика устанавливается в свойстве bannerMediaRecovery у экземпляров классов MTRGNativeBannerAd и MTRGNativeBannerAdLoader. Допустимые значения: skip (по-умолчанию) и retry.
Если MTRGNativeBannerAd не удалось загрузить медиа файлы при автозагрузке, то при:
- skip, SDK закончит загрузку всей рекламы и вызовет метод делегата onLoadFailedWithError:nativeBannerAd:
- retry, SDK будет повторять загрузку медиа указанное количество раз. Если медиа файлы все-таки не удастся загрузить, то в делегате вызовется onLoadFailedWithError:nativeBannerAd:.
Если MTRGNativeBannerAdLoader не удалось загрузить медиа файлы в баннере при автозагрузке, то при:
- skip, SDK пропустит этот баннер. Причем на загрузку остальных баннеров лоадере это не повлияет.
- retry, SDK будет повторять загрузку медиа для этого баннера указанное количество раз. Если ему все-таки не удастся их загрузить, то SDK пропустит такой баннер.
Политика также учитывается и при выключенной автозагрузке, когда медиа файлы загружаются асинхронно в момент вызова метода registerView.
При выключенной автозагрузке, если MTRGNativeBannerAd не удалось загрузить медиа файлы в registerView, то при:
- skip, SDK отменит загрузку медиа файлов, которые еще не загрузились, и вызовет метод onMediaLoadFailedWithNativeBannerAd: у mediaDelegate.
- retry, SDK будет повторять загрузку медиа файлов указанное количество раз. Если ему все-таки не удастся их загрузить, то в mediaDelegate вызовется метод onMediaLoadFailedWithNativeBannerAd:.
Помимо политики загрузки, есть возможность задать таймаут для загрузки медиа файлов. Устанавливается он в свойство bannerMediaTimeout и действует на медиа файлы в рамках баннера.
Автозагрузка изображений
По-умолчанию загружаются и кэшируются все изображения рекламного баннера. Вы можете выключить автоматическую загрузку изображений, но необходимо учитывать, что на их загрузку потребуется дополнительное время, что создаст дополнительную задержку показа рекламы в вашем приложении.
_ad.cachePolicy = MTRGCachePolicyNone;
[_ad load];
Допустимые значения: MTRGCachePolicyAll (по-умолчанию), MTRGCachePolicyImages, MTRGCachePolicyNone.
Если предзагрузка включена, то соответствующие изображения будут загружены и сохранены в кэш параллельно с загрузкой основных данных рекламного баннера.
Если предзагрузка изображений выключена, то они будут асинхронно и автоматически загружены в момент вызова метода registerView. Дополнительных действий не требуется.
Уведомления о загрузке медиа файлов
Для того чтобы получать уведомления о загрузке медиа файлов (в случае не автоматической загрузки) необходимо реализовать протокол MTRGNativeBannerAdMediaDelegate и установить свойство mediaDelegate у объекта MTRGNativeBannerAd.
@protocol MTRGNativeBannerAdMediaDelegate <NSObject>
- (void)onIconLoadWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd;
- (void)onAdChoicesIconLoadWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd;
- (void)onMediaLoadFailedWithNativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd;
@end
Уведомления о закрытии рекламы и их управление
Для того, чтобы получать уведомления о закрытии рекламы и управлять закрытием рекламы необходимо в свойство adChoicesOptionDelegate установить делегат, реализующий протокол MTRGNativeBannerAdChoicesOptionDelegate. Протокол содержит несколько методов:
- shouldCloseAutomatically – говорит SDK о том, стоит ли автоматически закрывать рекламу. Если метод возвращает YES, то SDK автоматически скроет рекламу. Если NO, то возможность скрыть предоставляется разработчику. Метод опциональный и по умолчанию возвращает YES;
- onCloseAutomatically: уведомляет разработчика, что реклама была скрыта автоматически, средствами SDK. Таким образом, этот метод вызовется, только если shouldCloseAutomatically вернет YES;
- closeIfAutomaticallyDisabled: уведомляет разработчика, что ему нужно скрыть рекламу самостоятельно. Таким образом, этот метод вызовется, только если shouldCloseAutomatically вернет NO.
Показ рекламных объявлений
После успешной загрузки данных вы можете использовать свойства полученного экземпляра баннера для заполнения вашего визуального компонента. Доступность свойств зависит от типа рекламируемого объекта — для приложений и сайтов они различаются.
Для показа иконки следует использовать MTRGIconAdView, предоставляемый SDK.
После заполнения визуального компонента вы должны зарегистрировать его в экземпляре MTRGNativeBannerAd, используя метод registerView. Если вы собираетесь использовать этот же визуальный компонент для показа других рекламных объявлений, вам необходимо предварительно вызвать метод unregisterView у текущего экземпляра MTRGNativeBannerAd до вызова registerView у другого экземпляра. Обработка показов и кликов осуществляется автоматически, при этом приложение не должно блокировать или перехватывать пользовательские события на этом визуальном компоненте. Ниже описаны доступные свойства и приведены примеры заполнения визуальных компонентов для различных типов рекламируемых объектов.
Визуальные компоненты (как стандартные, так и собственные) следует положить внутрь контейнера MTRGNativeAdContainer.При этом в метод registerView можно передавать как сам компонент, так и контейнер.
При создании контейнера, визуальный компонент adView будет добавлен как subview в контейнер и растянут по размерам контейнера.
Чтобы получить высоту визуального компонента в зависимости от его ширины (требуется для встраивания в TableView/CollectionView), необходимо вызвать метод sizeThatFits у контейнера (вызов метода проксируется в adView).
После создания контейнера нужно установить соответствие между доступными свойствами визуального компонента и свойствами контейнера.
- (void)onLoadWithNativeBanner:(MTRGNativeBanner *)banner nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
// Заголовок рекламного объявления
NSString *title = banner.title;
// Возрастное ограничение. Может быть nil
NSString *ageRestrictions = banner.ageRestrictions;
// Дисклеймер. Может быть nil
NSString *disclaimer = banner.disclaimerInfo.text;
// Текст метки "Реклама"
NSString *advertisingLabel = banner.advertisingLabel;
// Иконка
MTRGImageData *icon = banner.icon;
// Текст действия для кнопки
NSString *ctaText = banner.ctaText;
// Свойства, доступные только для объявлений, рекламирующих приложения
if (banner.navigationType == MTRGNavigationTypeStore))
{
// Рейтинг приложения (0-5)
NSNumber *rating = banner.rating;
// Количество оценок
NSUInteger votes = banner.votes;
}
// Свойства, доступные только для объявлений, рекламирующих сайты
else if (banner.navigationType == MTRGNavigationTypeWeb)
{
// Домен сайта
NSString *domain = banner.domain;
}
// Пример заполнения визуального компонента
UIView *adView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 300, 50)];
MTRGIconAdView *iconAdView = [MTRGNativeViewsFactory createIconAdView];
iconAdView.frame = CGRectMake(0, 0, 50, 50);
UILabel *titleLabel = [[UILabel alloc] initWithFrame:CGRectMake(60, 15, 140, 20)];
titleLabel.text = title;
UIButton *ctaButton = [[UIButton alloc] initWithFrame:CGRectMake(210, 10, 80, 30)];
[ctaButton setTitle:ctaText forState:UIControlStateNormal];
[adView addSubview:titleLabel];
[adView addSubview:iconAdView];
[adView addSubview:ctaButton];
MTRGNativeAdContainer *containerView = [MTRGNativeAdContainer createWithAdView:adView];
containerView.titleView = titleLabel;
containerView.iconView = iconAdView;
containerView.ctaView = ctaButton;
// Регистрируем визуальный компонент
[nativeBannerAd registerView:containerView withController:self];
// Добавляем на экран
[self.view addSubview:containerView];
}
Иконка AdChoices
myTarget SDK автоматически добавляет иконку AdChoices в каждый визуальный компонент. По умолчанию иконка добавляется в правый верхний угол визуального компонента, но вы вы можете выбрать предпочитаемый угол с помощью свойства adChoicesPlacement.
...
_ad.adChoicesPlacement = MTRGAdChoicesPlacementTopRight;
[_ad load];
Ручное позиционирование иконки AdChoices
Для ручного позиционирования иконки нужно выставить свойство adChoicesPlacement в значение MTRGAdChoicesPlacementManual. После чего при настройке визуального компонента нужно создать MTRGAdChoicesView и добавить его на рекламный компонент. Так вы сможете управлять позицией и размером иконки AdChoices, а также установить свою картинку. Если картинка не была установлена, то SDK поставить свою иконку AdChoices в MTRGAdChoicesView после того, как вы зарегистрируете визуальный компонент в объекте рекламы.
- (void)setupAdChoicesView
{
_ad.adChoicesPlacement = MTRGAdChoicesPlacementManual;
MTRGAdChoicesView *adChoicesView = MTRGNativeViewsFactory.createAdChoicesView;
// Устанавливаем свою картинку
adChoicesView.imageView.image = [UIImage imageNamed:@"AdChoices"];
[_adView addSubview:adChoicesView];
// Можно использовать Autolayout или фреймы для расположения и указания размеров adChoicesView
}
Ручная отрисовка иконки AdChoices
Чтобы полностью управлять компонентом отображения AdChoices, нужно свойство adChoicesPlacement выставить в значение MTRGAdChoicesPlacementDrawingManual. Тогда создание, отображение контента, размещение иконки и обработка нажатия полностью отдается разработчикам. Однако SDK предоставляет иконку AdChoices, которую вы можете использовать в своем компоненте (пункты «Автозагрузка изображение и видео» и «Уведомление об успешной загрузке ассетов»). Получить информацию о наличии AdChoices (свойство hasAdChoices) и о иконке (свойство adChoicesIcon) можно у MTRGNativeBanner. Чтобы уведомить SDK о том, что иконка AdChoices была нажата, у объекта рекламы нужно вызвать метод handleAdChoicesClickWithController:sourceView:.
- (void)setupAdChoicesView
{
_ad.adChoicesPlacement = MTRGAdChoicesPlacementDrawingManual;
_adChoicesButton = UIButton.new;
[_adChoicesButton setImage:_ad.banner.adChoicesIcon.image forState:UIControlStateNormal];
[_adChoicesButton addTarget:self action:@selector(adChoicesClick) forControlEvents:UIControlEventTouchUpInside];
[_adView addSubview:_adChoicesButton];
// Можно использовать Autolayout или фреймы для расположения и указания размеров adChoicesImageView
}
// Уведомляем SDK о том, что компонент AdChoices был нажат
- (void)adChoicesClick
{
[_ad handleAdChoicesClickWithController:self sourceView:_adChoicesButton];
}
Настройка кликабельной области
В приведенном выше примере визуальный компонент регистрируется с помощью метода registerView:withController. В этом случае вся область визуального компонента является кликабельной. MyTarget SDK предоставляет возможность указать конкретные визуальные компоненты, клики на которые будут отслеживаться. Для этого воспользуйтесь методом registerView:withController:withClickableViews:
- (void)onLoadWithNativeBanner:(MTRGNativeBanner *)banner nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
...
...
...
// Регистрируем визуальный компонент, с кликабельными заголовком и кнопкой призыва к действию
[nativeBannerAd registerView:adView withController:self withClickableViews:@[titleLabel, ctaButton]];
// Добавляем на экран
[self.view addSubview:adView];
}
Управление отображением меню AdChoices
Чтобы управлять отображением опций AdChoices нужно в соответствующий инициализатор передать объект, реализующий протокол MTRGMenuFactory. Протокол требует реализовать метод для создания меню. Меню же должно реализовывать протокол MTRGMenu. По умолчанию SDK использует UIAlertController со стилем actionSheet.
// Пример реализации меню
// Добавляем модель MTRGMenuAction в _items. Массив объектов, которые нужно будет показать в меню
- (void)addMenuAction:(nonnull MTRGMenuAction *)action
{
[_items addObject:action];
}
// На основе _items создаем UIAlertController и отображаем его
- (void)presentInViewController:(nonnull UIViewController *)viewController sourceView:(nullable UIView *)sourceView
{
UIAlertControllerStyle style = UIAlertControllerStyleAlert;
UIAlertController *alert = [UIAlertController alertControllerWithTitle:nil message:nil preferredStyle:style];
for (MTRGMenuAction *item in _items.copy)
{
UIAlertActionStyle actionStyle = (item.style == MTRGMenuActionStyleDefault) ? UIAlertActionStyleDefault : UIAlertActionStyleCancel;
UIAlertAction *action = [UIAlertAction actionWithTitle:item.title
style:actionStyle
handler:^(UIAlertAction * _Nonnull action)
{
[item handleClick];
}];
[alert addAction:action];
}
[viewController presentViewController:alert animated:YES completion:nil];
}
Использование готового визуального компонента
MyTarget SDK предоставляет готовый настраиваемый визуальный компонент, внешний вид которого вы можете настраивать под дизайн своего приложения.
Ниже приведены примеры и описаны доступные для настройки свойства.
MTRGNativeBannerAdView
- (void)onLoadWithNativeBanner:(MTRGNativeBanner *)banner nativeBannerAd:(MTRGNativeBannerAd *)nativeBannerAd
{
// Создаем визуальный компонент
MTRGNativeBannerAdView *adView = [MTRGNativeViewsFactory createNativeBannerAdView];
adView.banner = banner;
// Доступные для настройки внутренние визуальные компоненты
UILabel *titleLabel = adView.titleLabel;
MTRGIconAdView *iconAdView = adView.iconAdView;
UILabel *domainLabel = adView.domainLabel;
UILabel *disclaimerLabel = adView.disclaimerLabel;
MTRGStarsRatingLabel *ratingStarsView = adView.ratingStarsLabel;
UILabel *votesLabel = adView.votesLabel;
UIView *buttonView = adView.buttonView;
UILabel *buttonToLabel = adView.buttonToLabel;
UILabel *ageRestrictionsLabel = adView.ageRestrictionsLabel;
UILabel *adLabel = adView.adLabel;
// Отступы
UIEdgeInsets titleMargins = adView.titleMargins;
UIEdgeInsets domainMargins = adView.domainMargins;
UIEdgeInsets disclaimerMargins = adView.disclaimerMargins;
UIEdgeInsets iconMargins = adView.iconMargins;
UIEdgeInsets ratingStarsMargins = adView.ratingStarsMargins;
UIEdgeInsets votesMargins = adView.votesMargins;
UIEdgeInsets buttonMargins = adView.buttonMargins;
UIEdgeInsets buttonCaptionMargins = adView.buttonCaptionMargins;
UIEdgeInsets adLabelMargins = adView.adLabelMargins;
UIEdgeInsets ageRestrictionsMargins = adView.ageRestrictionsMargins;
// Регистрируем визуальный компонент
[nativeBannerAd registerView:adView withController:self];
// Добавляем на экран
[self.view addSubview:adView];
}
Загрузка нескольких баннеров
MyTarget SDK предоставляет класс MTRGNativeBannerAdLoader, который даёт возможность загрузить от 1 до 20 баннеров одним запросом. Для MTRGNativeBannerAdLoader вы можете настроить все те же параметры, которые доступны для настройки в MTRGNativeBannerAd (например, параметры пола и возраста пользователя, автозагрузку изображений и видео). myTarget SDK не гарантирует, что будет загружено количество баннеров, указанное в параметре COUNT - этот параметр указывает на максимальное количество баннеров, которое вы хотите получить.
// Включение режима отладки
// [MTRGManager setDebugMode:YES];
// Создаем MTRGNativeBannerAdLoader
MTRGNativeBannerAdLoader *nativeBannerAdLoader = [MTRGNativeBannerAdLoader loaderForCount:COUNT slotId:YOUR_SLOT_ID];
// Загружаем баннеры
[nativeBannerAdLoader loadWithCompletionBlock:^(NSArray<MTRGNativeBannerAd *> * _Nonnull nativeBannerAds, NSError * _Nullable error)
{
for (MTRGNativeBannerAd *nativeBannerAd in nativeBannerAds)
{
// Устанавливаем делегат
nativeBannerAd.delegate = self;
MTRGNativeBanner *banner = nativeBannerAd.banner;
// Код, аналогичный методу onLoadWithNativeBanner протокола MTRGNativeBannerAdDelegate
}
}];
Полученный массив будет содержать от 0 до COUNT объектов MTRGNativeBannerAd - каждый из них содержит уже загруженный MTRGNativeBanner и с каждым из них надо работать так же, как описано в этой документации выше, начиная с вызова метода onLoadWithNativeBanner.