Android SDK: In-stream видео


myTarget SDK предоставляет возможность показывать in-stream видео-рекламу в своем приложении, во время просмотра видео. Реклама может быть показана перед началом показа видео (preroll), во время показа (midroll) и после показа (postroll). SDK загружает данные и предоставляет приложению возможность показывать рекламу как в своем видео-плеере, так и в плеере приложения.

Инициализация

Для показа рекламного видео в вашем приложении необходимо создать экземпляр класса InstreamAd. Для создания экземпляра InstreamAd необходимо указать ваш slotId. Для каждого видео в приложении требуется создавать свой экземпляр класса InstreamAd.
private InstreamAd ad;
 
private void initAd()
{
    
    // Включение режима отладки
    // InstreamAd.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);
}

Интерфейс InstreamAdPlayer

Методы интерфейса InstreamAdPlayer вызываются экземпляром InstreamAd. Вызывать их самостоятельно не требуется.
1. Длительность рекламного видео
float getAdVideoDuration();
2. Текущая позиция рекламного видео. Метод вызывается многократно во время воспроизведения рекламного видео и должен отдавать актуальное значение в секундах.
float getAdVideoPosition();
3. Устанавливает слушатель плеера
void setAdPlayerListener(AdPlayerListener listener);
4. Визуальное представление плеера, обычно this.
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 при наступлении определенных событий.
void onAdVideoStarted();
Метод должен быть вызван после успешного начала воспроизведения рекламного видео, как ответ на вызов метода playAdVideo().
void onAdVideoPaused();
Метод должен быть вызван после приостановки проигрывания рекламного видео, как ответ на вызов метода pauseAdVideo().
void onAdVideoResumed();
Метод должен быть вызван после возобновления проигрывания рекламного видео, как ответ на вызов метода resumeAdVideo().
void onAdVideoStopped();
Метод должен быть вызван после остановки проигрывания рекламного видео, как ответ на вызов метода stopAdVideo().
void onAdVideoError(String message);
Метод должен быть вызван при возникновении какой-либо ошибки при проигрывании рекламного видео.
void onAdVideoCompleted();
Метод должен быть вызван при завершении проигрывания рекламного видео.
void onVolumeChanged(float volume);
Метод должен быть вызван при изменении громкости.

Использование плеера SDK

myTarget SDK предоставляет готовый плеер для проигрывания рекламы. Для использования плеера SDK достаточно вызвать метод useDefaultPlayer() у созданного экземпляра InstreamAd и добавить плеер на экран приложения.
private InstreamAd ad;
 
private void initAd()
{
    // Создаем экземпляр InstreamAd
    ad = new InstreamAd(YOUR_SLOT_ID, this);
     
    // Устанавливаем плеер SDK
    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)
        {
            // Проигрывание всех рекламных видео в рекламной секции завершено
        }
    });
         
    // Запускаем загрузку данных
    ad.load();
}

Показ рекламных объявлений

После успешной загрузки данных вы можете запустить показ рекламных секций. Каждая секция секция может содержать несколько рекламных видео, после начала проигрывания каждого будет вызван метод onBannerStart в установленном слушателе InstreamAdListener, после завершения проигрывания каждого видео будет вызван метод onBannerComplete. После завершения проигрывания всех рекламных видео в запущенной секции будет вызван метод onComplete - именно его вы должны использовать для дальнейших действий, он будет вызван даже если в процессе проигрывания произошла ошибка и был вызван метод onError.

Показ preroll и postroll секций

Для показа preroll секции необходимо перед началом показа видео вызвать метод startPreroll у экземпляра InstreamAd.

Для показа postroll секции необходимо после окончания показа видео вызвать метод startPostroll.
// Перед началом показа основного видео
ad.startPreroll();
 
// После показа основного видео
ad.startPostroll();

Показ midroll секции

Для показа midroll секции в какой-то позиции видео необходимо после создания экземпляра InstreamAd задать массив позиций, на которых планируется показ midroll секции. Позиции можно задавать как в секундах, так и в процентах от длительности видео.

После успешной загрузки данных станет доступен массив позиций, для которых есть рекламные видео. То есть если были заданы позиции на первой и пятой секунды, а рекламные видео в загруженных данных есть только для первой, то в доступном массиве будет только одна первая позиция.

Если позиции не были заданы приложением, они будут установлены сервером. Если массив позиций после загрузки оказался пустой, значит, данных для показа 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;
Ширина и высота рекламного видео.
public String ctaText;
Текст для call-to-action кнопки.

Обработка кликов

Приложение должно самостоятельно отслеживать клики по рекламному видео (как правило, по cta кнопке) и вызывать метод handleClick в экземпляре InstreamAd для обработки клика и перехода на рекламируемый сайт или приложение.
private void onAdClick()
{
    ad.handleClick();
}

Управление состоянием

У экземпляра InstreamAd доступны следующие методы управления.
public void pause()
Приостанавливает проигрывание рекламного видео.
public void resume()
Возобновляет проигрывание рекламного видео.
public void stop()
Останавливает показ рекламной секции.
public void skip()
Останавливает показ рекламной секции, если это было сделано пользователем (нажатие на кнопку «Пропустить» или «Закрыть»).
public void skipBanner()
Останавливает текущее рекламное видео и переходит к следующему, если это было сделано пользователем (нажатие на кнопку «Пропустить» или «Закрыть»).
public void setVolume(float volume)
Устанавливает громкость от 0 до 1.
public void setLoadingTimeout(int loadingTimeout)
Устанавливает таймаут на загрузку рекламы в секундах. В случае если по истечению указанного интервала не удалось получить баннеры, будет вызван коллбек 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.
Вам помогла эта статья?
Да
Нет