VK Ad SDK предоставляет возможность показывать рекламу в своем приложении, используя собственные визуальные компоненты.
SDK загружает данные и предоставляет приложению модель рекламного объявления с определенными свойствами для заполнения визуального компонента, а также методы для подсчета показов и обработки кликов.
SDK также предоставляет набор готовых настраиваемых визуальных компонентов, которые вы можете использовать в вашем приложении, вместо создания собственных.
Инициализация
Для показа нативных рекламных объявлений в вашем приложении необходимо создать экземпляр класса NativeAd. Для создания экземпляра NativeAd необходимо указать ваш slotId.
private NativeAd ad;private void initAd(){ // Включение режима отладки // MyTargetManager.setDebugMode(true); // Создаем экземпляр NativeAd ad = new NativeAd(YOUR_SLOT_ID, this);}
Загрузка рекламных объявлений
Для получения уведомлений (таких как успешная загрузка данных или ошибка загрузки, клик по рекламному объявлению) необходимо создать экземпляр NativeAdListener и установить его в качестве слушателя событий, после чего можно запустить загрузку данных.
private NativeAd ad;private void initAd(){ // Создаем экземпляр NativeAd ad = new NativeAd(YOUR_SLOT_ID, this); // Устанавливаем слушатель событий ad.setListener(new NativeAd.NativeAdListener() { @Override public void onLoad(NativePromoBanner banner, NativeAd ad) { } @Override public void onNoAd(String reason, NativeAd ad) { } @Override public void onClick(NativeAd ad) { } @Override public void onShow(NativeAd ad) { } @Override public void onVideoPlay(NativeAd ad) { } @Override public void onVideoPause(NativeAd ad) { } @Override public void onVideoComplete(NativeAd ad) { } }); // Запускаем загрузку данных ad.load();}
Автозагрузка изображений и видео
По умолчанию загружаются изображения и видео. Вы можете выключить автоматическую загрузку изображений и видео, но необходимо учитывать, что на их загрузку потребуется дополнительное время, что создаст дополнительную задержку показа рекламы в вашем приложении.
ad.setCachePolicy(CachePolicy.NONE);ad.load();
Допустимые значения: CachePolicy.ALL (по умолчанию), CachePolicy.IMAGE, CachePolicy.VIDEO, CachePolicy.NONE.
Если предзагрузка включена, то соответствующие изображения будут загружены и сохранены в кэш параллельно с загрузкой основных данных рекламного баннера.
Если предзагрузка изображений выключена, то они будут асинхронно и автоматически загружены в момент вызова метода registerView. Дополнительных действий не требуется.
Уведомления об успешной загрузке ассетов
Есть возможность поставить слушатель для получения уведомлений об успешной загрузке файлов изображений image и icon в случае автоматической загрузки.
ad.setMediaListener(new NativeAdMediaListener() { @Override public void onIconLoad(@NonNull NativeAd ad) { // уведомление об успешной загрузке иконки }
@Override public void onImageLoad(@NonNull NativeAd ad) { // уведомление об успешной загрузке основного изображения } });ad.load();
Показ рекламных объявлений
После успешной загрузки данных вы можете использовать свойства полученного экземпляра баннера для заполнения вашего визуального компонента. Доступность свойств зависит от типа рекламируемого объекта: для приложений и сайтов они различаются.
Для показа главной картинки, карусели и проигрывания видео вы должны использовать компонент MediaAdView, предоставляемый SDK.
Для показа иконки следует использовать IconAdView, предоставляемый SDK.
Визуальный компонент должен быть добавлен в контейнер com.my.target.nativeads.views.NativeAdContainer.
Элементам визуального компонента должны быть присвоены соответствующие id, поставляемые с SDK.
| Элемент рекламного View | Соответствующий id |
|---|---|
| Root View (ваш AdView) | R.id.nativeads_ad_view |
| Advertising Label | R.id.nativeads_advertising |
| Title | R.id.nativeads_title |
| Description | R.id.nativeads_description |
| Rating | R.id.nativeads_rating |
| Domain | R.id.nativeads_domain |
| Age Restrictions | R.id.nativeads_age_restrictions |
| Disclaimer | R.id.nativeads_disclaimer |
| Call-to-Action | R.id.nativeads_call_to_action |
| Icon | R.id.nativeads_icon |
| MediaAdView | R.id.nativeads_media_view |
После заполнения визуального компонента вы должны зарегистрировать его в экземпляре NativeAd, используя метод registerView.
Если вы собираетесь использовать этот же визуальный компонент для показа других рекламных объявлений, вам необходимо предварительно вызвать метод unregisterView у текущего экземпляра NativeAd до вызова registerView у другого экземпляра.
Обработка показов и кликов осуществляется автоматически, при этом приложение не должно блокировать или перехватывать пользовательские события на этом визуальном компоненте. Ниже описаны доступные свойства и приведены примеры заполнения визуальных компонентов для различных типов рекламируемых объектов.
@Overridepublic void onLoad(NativePromoBanner banner, NativeAd ad){ // Заголовок рекламного объявления String title = banner.getTitle(); // Основной текст String description = banner.getDescription(); // Возрастное ограничение. Может быть null String ageRestrictions = banner.getAgeRestrictions(); // Дисклеймер. Может быть null String disclaimer = banner.getDisclaimer(); // Текст метки "Реклама" String advertisingLabel = banner.getAdvertisingLabel(); // Иконка ImageData icon = banner.getIcon(); // Текст действия для кнопки String ctaText = banner.getCtaText(); // Свойства, доступные только для объявлений, рекламирующих приложения if (banner.getNavigationType().equals(NavigationType.STORE)) { // Рейтинг приложения (0-5) float rating = banner.getRating(); // Количество оценок int votes = banner.getVotes(); // Категория приложения String category = banner.getCategory(); // Подкатегория приложения String subcategory = banner.getSubcategory(); } // Свойства, доступные только для объявлений, рекламирующих сайты else if (banner.getNavigationType().equals(NavigationType.WEB)) { //Домен сайта String domain = banner.getDomain(); } // Пример заполнения визуального компонента Context context = YourActivity.this; LinearLayout adViewLayout = new LinearLayout(context); adViewLayout.setId(R.id.nativeads_ad_view); TextView titleView = new TextView(context); titleView.setId(R.id.nativeads_title); titleView.setText(title); adViewLayout.addView(titleView); TextView descriptionView = new TextView(context); descriptionView.setId(R.id.nativeads_description); titleView.setText(description); adViewLayout.addView(descriptionView); Button btn = new Button(context); btn.setId(R.id.nativeads_call_to_action); btn.setText(ctaText); adViewLayout.addView(btn); // Создаем MediaAdView MediaAdView mediaView = NativeViewsFactory.getMediaAdView(context); mediaView.setId(R.id.nativeads_media_view); // Создаем IconAdView IconAdView iconView = new IconAdView(context); mediaView.setId(R.id.nativeads_icon); adViewLayout.addView(mediaView); adViewLayout.addView(iconView); // Создаём контейнер для креатива NativeAdContainer nativeAdContainer = new NativeAdContainer(context); // Добавляем рекламный креатив в контейнер nativeAdContainer.addView(adViewLayout); // Регистрируем визуальный компонент ad.registerView(nativeAdContainer); // Добавляем на экран mainLayout.addView(nativeAdContainer, ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);}
Компоненты нативной рекламы
В библиотеке представлены как обязательные, так и опциональные элементы. Правила размещения рекламных объявлений требуют отображения только обязательных элементов.
Однако макеты с полным набором компонентов более кликабельные, поэтому мы рекомендуем использовать именно их.
| Компонент | Обязательность |
| Рекламная метка | Да |
| Возраст | Да |
| Дисклеймер | Да |
| Домен | Да |
| Заголовок | Да |
| Значок меню | Да |
| Иконка | Да, для рекламы приложений |
| Кнопка действия | Да |
| Медиа | Да |
| Описание | Нет |
| Рейтинг (для приложений) | Нет |
Используйте макет, который отображает весь набор обязательных и опциональных компонентов рекламы
Иконка AdChoices
VK Ad SDK автоматически добавляет иконку AdChoices в каждый визуальный компонент. По умолчанию иконка добавляется в правый верхний угол визуального компонента, но вы вы можете выбрать предпочитаемый угол с помощью метода setAdChoicesPlacement(int placement):
...ad.setAdChoicesPlacement(AdChoicesPlacement.TOP_RIGHT);ad.load();
Ручная настройка AdChoices
В случае если необходимо установить свое изображение для AdChoices, нужно использовать класс NativeAdChoicesView и передать туда изображение с помощью методов setImageBitmap() или setImageDrawable().
...NativeAdChoicesView myAdChoicesView = createMyAdChoicesView(); // создание своей NativeAdChoicesViewmyAdChoicesView.setImageBitmap(bitmap);myAdChoicesView.setImageDrawable(drawable);...
В случае если требуется ручное позиционирование AdChoicesView (выставление гравитации, маржинов) внутри своей View для показа нативной рекламы, требуется указать AdChoicesPlacement.MANUAL.
...ad.setAdChoicesPlacement(AdChoicesPlacement.MANUAL);ad.load();
Кастомизация кнопки AdChoices
Разработчик может сам отрисовать кнопку адчойсов так, как ему необходимо, но в таком случае для NativeAd нужно задать свойство AdChoicesPlacement.DRAWING_MANUAL. Также необходимо вызывать метод ad.handleAdChoicesClick(context) для обработки нажатия на адчойсы.
...ad.setAdChoicesPlacement(AdChoicesPlacement.DRAWING_MANUAL);ad.load();...customAdChoicesView.setOnClickListener(v->{ ad.handleAdChoicesClick(context)})
Чтобы получить иконку адчойсов, можно обратиться к объекту рекламы напрямую или использовать слушатель NativeAdChoicesListener, слушатель необходимо задавать перед загрузкой рекламы.
//получение иконки адчойсов через переменнуюad.getBanner().getAdChoicesIcon();...//получение иконки адчойсов через слушательad.setAdChoicesListener(new NativeAd.NativeAdChoicesListener() { @Override public void onAdChoicesIconLoad(@Nullable ImageData imageData, boolean success, @NonNull NativeAd ad) { customAdChoicesView.setImageBitmap(imageData.getBitmap) }});
Кастомизация отрисовки опций AdChoices
Для изменения дизайна отрисовки опций AdChoices необходимо в конструкторе NativeAd передать объект, реализующий интерфейс MenuFactory, который в свою очередь должен должен возвращать объект реализующий интерфейс Menu.
MenuFactory menuFactory = new MenuFactory() { @Override @NonNull public Menu createMenu() { return new Menu() { @Override public void setListener(@Nullable Listener listener) { //слушатель, у которого нужно вызвать метод onActionClick(menuAction) при нажатии на тот элемент UI, который был отрисован с соответствующим заголовком menuAction } @Override public void addAction(@NonNull MenuAction menuAction) { // это объект который содержит в себе заголовок и тип опции адчойсов, эти объекты нужно нужно использовать при отрисовке } @Override public void present(@NonNull Context context) { // данный метод вызывается когда необходимо отобразить опции адчойсов с теми menuAction, которые были ранее получены из метода addAction() } @Override public void dismiss() { // данный метод вызывается когда необходимо закрыть отрисовку опций адчойсов } }; } };...ad = new NativeAd(YOUR_SLOT_ID, menuFactory, this);ad.load();
Управление закрытием рекламы
Для того чтобы получать уведомления о закрытии рекламы и управлять закрытием рекламы, необходимо передать объект, реализующий интерфейс NativeAdChoicesOptionListener. Интерфейс содержит несколько методов.
- boolean shouldCloseAutomatically() — говорит SDK о том, стоит ли автоматически закрывать рекламу. Если метод возвращает true, то SDK автоматически скроет рекламу. Если false, то возможность скрыть предоставляется разработчику.
- onCloseAutomatically() — уведомляет разработчика, что реклама была скрыта автоматически, средствами SDK. Таким образом, этот метод вызовется, только если shouldCloseAutomatically вернет true.
- closeIfAutomaticallyDisabled() — уведомляет разработчика, что ему нужно скрыть рекламу самостоятельно. Таким образом, этот метод вызовется, только если shouldCloseAutomatically вернет false.
NativeAd.NativeAdChoicesOptionListener adChoicesOptionListener = new NativeAd.NativeAdChoicesOptionListener(){ @Override public boolean shouldCloseAutomatically() { return false; } @Override public void onCloseAutomatically(@NonNull NativeBannerAd ad) { } @Override public void closeIfAutomaticallyDisabled(@NonNull NativeBannerAd ad) { }}; ad.setAdChoicesOptionListener(adChoicesOptionListener);
Настройка кликабельной области
В приведенном выше примере визуальный компонент регистрируется с помощью метода registerView(View view). В этом случае вся область визуального компонента является кликабельной. VK Ad SDK предоставляет возможность указать конкретные визуальные компоненты, клики на которые будут отслеживаться. Для этого воспользуйтесь методом registerView(View view, List<View> clickableViews):
@Overridepublic void onLoad(NativePromoBanner banner, NativeAd ad){ ... ... ... // Создаем массив кликабельных визуальных компонентов, заголовка и кнопки призыва к действию ArrayList<View> clickableViews = new ArrayList<>(); clickableViews.add(titleView); clickableViews.add(btn); // Регистрируем визуальный компонент, с кликабельными заголовком и кнопкой призыва к действию ad.registerView(adViewLayout, clickableViews); // Добавляем на экран mainLayout.addView(adViewLayout, ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);}
Использование готового визуального компонента
VK Ad SDK предоставляет готовый настраиваемый визуальный компонент, внешний вид которого вы можете настраивать под дизайн своего приложения.
Ниже приведены примеры и описаны доступные для настройки свойства.
NativeAdView
public void onLoad(NativePromoBanner banner, NativeAd ad){ // Создаем визуальный компонент NativeAdView nativeAdView = NativeViewsFactory.getNativeAdView(ad, YourActivity.this); // Доступные для настройки внутренние визуальные компоненты TextView advLabelView = nativeAdView.getAdvertisingTextView(); TextView ageRestrictionView = nativeAdView.getAgeRestrictionTextView(); TextView disclaimerView = nativeAdView.getDisclaimerTextView(); TextView titleView = nativeAdView.getTitleTextView(); TextView descriptionView = nativeAdView.getDescriptionTextView(); Button ctaBtn = nativeAdView.getCtaButtonView(); TextView votesView = nativeAdView.getVotesTextView(); StarsRatingView starsRatingView = nativeAdView.getStarsRatingView(); TextView domainView = nativeAdView.getDomainOrCategoryTextView(); MediaAdView mediaView = nativeAdView.getMediaAdView(); IconAdView iconView = nativeAdView.getIconImageView(); // Создаём контейнер для креатива NativeAdContainer nativeAdContainer = new NativeAdContainer(context); // Добавляем рекламный креатив в контейнер nativeAdContainer.addView(nativeAdView); // Регистрируем визуальный компонент ad.registerView(nativeAdContainer); // Добавляем на экран mainLayout.addView(nativeAdContainer, ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT);}
Загрузка нескольких баннеров
VK Ad SDK предоставляет класс NativeAdLoader, который дает возможность загрузить от 1 до 20 баннеров одним запросом. Для NativeAdLoader вы можете настроить все те же параметры, которые доступны для настройки в NativeAd (например, параметры пола и возраста пользователя, автозагрузку изображений и видео).
VK Ad SDK не гарантирует, что будет загружено количество баннеров, указанное в параметре COUNT — этот параметр указывает на максимальное количество баннеров, которое вы хотите получить.
// Включение режима отладки// MyTargetManager.setDebugMode(true); // Создаем NativeAdLoaderNativeAdLoader nativeAdLoader = NativeAdLoader.newLoader(YOUR_SLOT_ID, COUNT, this);// Устанавливаем OnLoad коллбек и загружаем баннерыnativeAdLoader.setOnLoad(new OnLoad(){ @Override public void onLoad(@NonNull List<NativeAd> ads) { for (NativeAd ad : ads) { // Устанавливаем слушатель событий ad.setListener(nativeAdListener); NativePromoBanner promoBanner = ad.getBanner(); // Код, аналогичный методу onLoad интерфейса NativeAdListener } }}).load();
Полученный массив будет содержать от 0 до COUNT объектов NativeAd — каждый из них содержит уже загруженный NativePromoBanner и с каждым из них надо работать так же, как описано в этой документации выше, начиная с вызова метода onLoad.