myTarget SDK предоставляет возможность показывать in-stream видеорекламу в своем приложении во время просмотра видео. Реклама может быть показана перед началом показа видео (preroll), во время показа (midroll) и после показа (postroll). SDK загружает данные и предоставляет приложению возможность показывать рекламу как в своем видео-плеере, так и в плеере приложения.
Инициализация
Для показа рекламного видео в вашем приложении необходимо создать экземпляр класса InstreamAd. Для создания экземпляра InstreamAd необходимо указать ваш slotId. Для каждого видео в приложении требуется создавать свой экземпляр класса InstreamAd.
private InstreamAd ad;
private void initAd()
{
// Включение режима отладки
// MyTargetManager.setDebugMode(true);
// Создаем экземпляр InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
}
Использование плеера приложения
Для проигрывания рекламы в плеере приложения, он должен реализовывать интерфейс InstreamAdPlayer и уведомлять установленный ему слушатель AdPlayerListener. Для использования своего плеера надо вызвать метод setPlayer(InstreamAdPlayer player) у созданного экземпляра InstreamAd.
private InstreamAd ad;
private void initAd()
{
// Создаем экземпляр InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Устанавливаем плеер
ad.setPlayer(YOUR_PLAYER);
}
Кнопка adChoices
Разработчик должен сам отрисовать кнопку адчойсов так, как ему необходимо. Также необходимо вызывать метод ad.handleAdChoicesClick(context) для обработки нажатия на адчойсы. По умолчанию для InstreamAd кнопка адчойсов не отображается.
customAdChoicesView.setOnClickListener(v->
{
ad.handleAdChoicesClick(context)
})
Кастомизация отрисовки опций adChoices
Для изменения дизайна отрисовки опций адчойсов необходимо в конструкторе InstreamAd передать объект реализующий интерфейс MenuFactory, который в свою очередь должен возвращать объект реализующий интерфейс Menu. Если параметр не передать SDK, по умолчанию будет отображать стандартную реализацию показа опций меню адчойсов.
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 InstreamAd(YOUR_SLOT_ID, menuFactory, this);
ad.load();
Интерфейс InstreamAdPlayer
1. Длительность рекламного видео
float getAdVideoDuration();
2. Текущая позиция рекламного видео. Метод вызывается многократно во время воспроизведения рекламного видео и должен отдавать актуальное значение в секундах.
float getAdVideoPosition();
3. Устанавливает слушатель плеера
void setAdPlayerListener(AdPlayerListener listener);
4. Визуальное представление плеера.
View getView();
5. Устанавливает громкость от 0 до 1.
void setVolume(float volume);
6. Запускает воспроизведение рекламного видео.
- uri - путь к видео
- width - ширина видео в пикселях
- height - высота видео в пикселях
void playAdVideo(Uri uri, int width, int height);
7. Приостанавливает проигрывание рекламного видео.
void pauseAdVideo();
8. Возобновляет проигрывание рекламного видео.
void resumeAdVideo();
9. Останавливает проигрывание рекламного видео.
void stopAdVideo();
Интерфейс InstreamAdPlayer.AdPlayerListener
Методы обратного вызова интерфейса AdPlayerListener для установленного слушателя должны быть вызваны плеером в ответ на вызовы методов интерфейса InstreamAdPlayer при наступлении определенных событий.
Метод должен быть вызван после успешного начала воспроизведения рекламного видео, как ответ на вызов метода playAdVideo().
void onAdVideoStarted();
Метод должен быть вызван после приостановки проигрывания рекламного видео, как ответ на вызов метода pauseAdVideo().
void onAdVideoPaused();
Метод должен быть вызван после возобновления проигрывания рекламного видео, как ответ на вызов метода resumeAdVideo().
void onAdVideoResumed();
Метод должен быть вызван после остановки проигрывания рекламного видео, как ответ на вызов метода stopAdVideo().
void onAdVideoStopped();
Метод должен быть вызван при возникновении какой-либо ошибки при проигрывании рекламного видео.
void onAdVideoError(String message);
Метод должен быть вызван при завершении проигрывания рекламного видео.
void onAdVideoCompleted();
Метод должен быть вызван при изменении громкости.
void onVolumeChanged(float volume);
Использование плеера SDK
myTarget SDK предоставляет один из двух готовый плеер для проигрывания рекламы. Для использования плеера SDK достаточно вызвать метод useDefaultPlayer() у созданного экземпляра InstreamAd и добавить плеер на экран приложения. При этом будет использоваться ExoPlayer. Если же указать useDefaultPlayer(false) то будет использован стандартный плеер Android SDK.
private InstreamAd ad;
private void initAd()
{
// Создаем экземпляр InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Устанавливаем плеер SDK
// В качестве параметра можно передать false, если хотим использовать стандартный плеер Android SDK вместо ExoPlayer
ad.useDefaultPlayer();
// Добавляем плеер на экран
layout.addView(ad.getPlayer().getView());
}
Загрузка рекламных объявлений
Для получения уведомлений (таких как успешная загрузка данных или ошибка загрузки, показ рекламного объявления) необходимо создать экземпляр InstreamAdListener и установить его в качестве слушателя событий, после чего можно запустить загрузку данных.
private InstreamAd ad;
private void initAd()
{
// Создаем экземпляр InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Устанавливаем слушатель событий
ad.setListener(new InstreamAd.InstreamAdListener()
{
@Override
public void onLoad(InstreamAd instreamAd)
{
// Данные успешно загружены
}
@Override
public void onNoAd(String reason, InstreamAd instreamAd)
{
// Данные не получены
}
@Override
public void onError(String reason, InstreamAd ad)
{
// При проигрывании рекламного видео произошла ошибка
}
@Override
public void onBannerStart(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Началось проигрывание рекламного видео
}
@Override
public void onBannerPause(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Проигрывание рекламного видео приостановлено
}
@Override
public void onBannerResume(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Проигрывание рекламного видео возобновлено
}
@Override
public void onBannerComplete(InstreamAd ad, InstreamAd.InstreamAdBanner instreamAdBanner)
{
// Проигрывание рекламного видео завершено
}
@Override
public void onBannerTimeLeftChange(float timeLeft, float duration, InstreamAd ad)
{
// Вызывается многократно во время воспроизведения рекламного видео, используется для обновления таймера до окончания показа рекламного видео
}
@Override
public void onComplete(String section, InstreamAd ad)
{
// Проигрывание всех рекламных видео в рекламной секции завершено
}
@Override
public void onBannerShouldClose()
{
// Вызывается когда проигрывание рекламы должно быть завершено разработчиком самостоятельно. Пример: ad.skip()
}
});
// Запускаем загрузку данных
ad.load();
}
Показ рекламных объявлений
После успешной загрузки данных вы можете запустить показ рекламных секций. Каждая секция секция может содержать несколько рекламных видео, после начала проигрывания каждого будет вызван метод onBannerStart в установленном слушателе InstreamAdListener, после завершения проигрывания каждого видео будет вызван метод onBannerComplete.
После завершения проигрывания всех рекламных видео в запущенной секции будет вызван метод onComplete - именно его вы должны использовать для дальнейших действий, он будет вызван даже если в процессе проигрывания произошла ошибка и был вызван метод onError.
Показ preroll и postroll секций
Для показа preroll секции необходимо перед началом показа видео вызвать метод startPreroll у экземпляра InstreamAd.
Для показа postroll секции необходимо после окончания показа видео вызвать метод startPostroll.
// Перед началом показа основного видео
ad.startPreroll();
// После показа основного видео
ad.startPostroll();
Показ midroll секции
Для показа midroll секции в какой-то позиции видео необходимо после создания экземпляра InstreamAd задать массив позиций, на которых планируется показ midroll секции. Позиции можно задавать как в секундах, так и в процентах от длительности видео.
После успешной загрузки данных станет доступен массив позиций, для которых есть рекламные видео. То есть если были заданы позиции на 1 и 5 секунды, а рекламные видео в загруженных данных есть только для первой, то в доступном массиве будет только одна первая позиция.
Если позиции не были заданы приложением, они будут установлены сервером. Если массив позиций после загрузки оказался пустой, значит, данных для показа midroll секции нет.
private InstreamAd ad;
private void initAd()
{
// Создаем экземпляр InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Устанавливаем позиции на первой и пятой секунде видео
ad.configureMidpoints(videoDuration, new float[]{1f,5f});
// или в процентах, на 10% и 50% видео
// ad.configureMidpointsPercents(videoDuration, new float[]{10f,50f});
// Устанавливаем слушатель событий
ad.setListener(new InstreamAd.InstreamAdListener()
{
@Override
public void onLoad(InstreamAd instreamAd)
{
// Данные успешно загружены
// Массив позиций (в секундах), доступных для показа midroll секции
adPositions = ad.getMidPoints();
}
...
});
// Запускаем загрузку данных
ad.load();
}
При достижении основным видео одной из позиций для midroll секции необходимо вызвать метод startMidroll и передать в него в качестве параметра эту позицию.
// Видео доигралось до 5-й секунды и для неё есть позиция в массиве adPositions
ad.startMidroll(adPositions[1]);
Доступные свойства рекламного видео
В методы onBannerStart и onBannerComplete слушателя InstreamAdListener передается экземпляр InstreamAdBanner, содержащий информацию о текущем рекламном видео, которая может быть использована приложением.
Длительность текущего рекламного видео в секундах.
public final float duration;
Разрешено ли закрывать рекламное видео во время проигрывания. Используется для управления показом кнопки «Закрыть» или «Пропустить».
public final boolean allowClose;
Время в секундах, через которое рекламное видео может быть закрыто. Используется для управления показом кнопки «Закрыть» или «Пропустить».
public final float allowCloseDelay;
Ширина и высота рекламного видео.
public final int videoWidth;
public final int videoHeight;
Текст для call-to-action кнопки.
public String ctaText;
Наличие адчойсов.
public boolean hasAdChoices;
Рекламный заголовок.
public String advertisingLabel;
Иконка адчойса.
public ImageData adChoicesIcon;
Обработка кликов
Приложение должно самостоятельно отслеживать клики по рекламному видео (как правило, по cta кнопке) и вызывать метод handleClick в экземпляре InstreamAd для обработки клика и перехода на рекламируемый сайт или приложение.
private void onAdClick()
{
ad.handleClick();
}
Управление состоянием
У экземпляра InstreamAd доступны следующие методы управления.
1. Приостанавливает проигрывание рекламного видео.
public void pause()
2. Возобновляет проигрывание рекламного видео.
public void resume()
3. Останавливает показ рекламной секции.
public void stop()
4. Останавливает показ рекламной секции, если это было сделано пользователем (нажатие на кнопку «Пропустить» или «Закрыть»).
public void skip()
5. Останавливает текущее рекламное видео и переходит к следующему, если это было сделано пользователем (нажатие на кнопку «Пропустить» или «Закрыть»).
public void skipBanner()
6. Устанавливает громкость от 0 до 1.
public void setVolume(float volume)
Устанавливает таймаут на загрузку рекламы в секундах. В случае если по истечению указанного интервала не удалось получить баннеры, будет вызван коллбек onNoAd. Значение по умолчанию — 10 секунд, минимальное значение — 5 секунд.
Пользовательские данные
Для лучшего подбора рекламных объявлений, вы можете дополнительно задать пол и возраст пользователя. Если ваше приложение использует собственную модель локализации, вы также можете указать язык выбранной локализации в формате ISO 639-1 («ru», «en», «fr» и т.д.).
Для задания пользовательских данных вам нужно воспользоваться свойством customParams.
private InstreamAd ad;
private void initAd()
{
// Создаем экземпляр InstreamAd
ad = new InstreamAd(YOUR_SLOT_ID, this);
// Получаем экземпляр дополнительных параметров CustomParams
CustomParams customParams = ad.getCustomParams();
// Задаем возраст
customParams.setAge(25);
// Задаем пол
customParams.setGender(CustomParams.Gender.MALE);
}
Примеры
Примеры интеграции доступны в нашем демоприложении на Github.