Android SDK: In-stream аудио


myTarget SDK предоставляет возможность проигрывать in-stream аудио-рекламу в своем приложении во время прослушивания аудио.

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

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

Для проигрывания рекламного аудио в вашем приложении необходимо создать экземпляр класса InstreamAudioAd. Для создания экземпляра InstreamAudioAd необходимо указать ваш slotId.

Для каждого аудио в приложении требуется создавать свой экземпляр класса InstreamAudioAd.

private InstreamAudioAd ad;
 
private void initAd()
{
    // Включение режима отладки
    // InstreamAudioAd.setDebugMode(true); 
    // Создаем экземпляр InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
}

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

Для проигрывания рекламы в плеере приложения он должен реализовывать интерфейс InstreamAudioAdPlayer и уведомлять установленный ему слушатель AdPlayerListener.

Для использования своего плеера надо вызвать метод setPlayer(InstreamAudioAdPlayer player) у созданного экземпляра InstreamAudioAd.
private InstreamAudioAd ad;
 
private void initAd()
{
    // Создаем экземпляр InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
     
    // Устанавливаем плеер
    ad.setPlayer(YOUR_PLAYER);
}

Интерфейс InstreamAudioAdPlayer

Методы интерфейса InstreamAudioAdPlayer вызываются экземпляром InstreamAudioAd. Вызывать их самостоятельно не требуется.
float getAdAudioDuration();
Длительность рекламного аудио
float getAdAudioPosition();
Текущая позиция рекламного аудио. Метод вызывается многократно во время проигрывания рекламного аудио и должен отдавать актуальное значение в секундах.
void setAdPlayerListener(AdPlayerListener listener);
Устанавливает слушатель плеера
Context getCurrentContext();
Текущий контекст.
void setVolume(float volume);
Устанавливает громкость от 0 до 1.
void playAdAudio(Uri uri);
Запускает воспроизведение рекламного аудио.

uri — путь к аудио
void pauseAdAudio();
Приостанавливает проигрывание рекламного аудио.
void resumeAdAudio();
Возобновляет проигрывание рекламного аудио.
void stopAdAudio();
Останавливает проигрывание рекламного аудио.

Интерфейс InstreamAudioAdPlayer.AdPlayerListener

Методы обратного вызова интерфейса AdPlayerListener для установленного слушателя должны быть вызваны плеером в ответ на вызовы методов интерфейса InstreamAudioAdPlayer при наступлении определенных событий.
void onAdAudioStarted();
Метод должен быть вызван после успешного начала воспроизведения рекламного аудио, как ответ на вызов метода playAdAudio().
void onAdAudioPaused();
Метод должен быть вызван после приостановки проигрывания рекламного видео, как ответ на вызов метода pauseAdVideo().
void onAdAudioResumed();
Метод должен быть вызван после возобновления проигрывания рекламного аудио, как ответ на вызов метода resumeAdAudio().
void onAdAudioStopped();
Метод должен быть вызван после остановки проигрывания рекламного аудио, как ответ на вызов метода stopAdAudio().
void onAdAudioError(String message);
Метод должен быть вызван при возникновении какой-либо ошибки при проигрывании рекламного аудио.
void onAdAudioCompleted();
Метод должен быть вызван при завершении проигрывания рекламного аудио.
void onVolumeChanged(float volume);
Метод должен быть вызван при изменении громкости.

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

Для получения уведомлений (таких как успешная загрузка данных или ошибка загрузки) необходимо создать экземпляр InstreamAudioAdListener и установить его в качестве слушателя событий, после чего можно запустить загрузку данных.
private InstreamAudioAd ad;
 
private void initAd()
{
    // Создаем экземпляр InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
     
    // Устанавливаем слушатель событий
    ad.setListener(new InstreamAudioAd.InstreamAudioAdListener()
    {
        @Override
        public void onLoad(InstreamAudioAd ad)
        {
            // Данные успешно загружены
        }
 
        @Override
        public void onNoAd(String reason, InstreamAudioAd ad)
        {
            // Данные не получены
        }
 
        @Override
        public void onError(String reason, InstreamAudioAd ad)
        {
            // При проигрывании рекламного аудио произошла ошибка
        }
 
        @Override
        public void onBannerStart(InstreamAudioAd ad, InstreamAudioAd.InstreamAudioAdBanner banner)
        {
            // Началось проигрывание рекламного аудио
        }
 
        @Override
        public void onBannerComplete(InstreamAudioAd ad, InstreamAudioAd.InstreamAudioAdBanner banner)
        {
            // Проигрывание рекламного аудио завершено
        }
 
        @Override
        public void onBannerTimeLeftChange(float timeLeft, float duration, InstreamAudioAd ad)
        {
            // Вызывается многократно во время воспроизведения рекламного аудио, используется для обновления таймера до окончания показа рекламного аудио
        }
 
        @Override
        public void onComplete(String section, InstreamAudioAd ad)
        {
            // Проигрывание всех рекламных аудио в рекламной секции завершено
        }
    });
         
    // Запускаем загрузку данных
    ad.load();
}

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

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

Каждая секция секция может содержать несколько рекламных аудио, после начала проигрывания каждого будет вызван метод onBannerStart в установленном слушателе InstreamAudioAdListener, после завершения проигрывания каждого аудио будет вызван метод onBannerComplete.

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

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

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

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

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

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

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

Если массив позиций после загрузки оказался пустой, значит данных для проигрывания midroll секции нет.
private InstreamAudioAd ad;
 
private void initAd()
{
    // Создаем экземпляр InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
     
    // Устанавливаем позиции на первой и пятой секунде аудио
    ad.configureMidpoints(videoDuration, new float[]{1f,5f});
    // или в процентах, на 10% и 50% аудио
    // ad.configureMidpointsPercents(audioDuration, new float[]{10f,50f});
 
    // Устанавливаем слушатель событий
    ad.setListener(new InstreamAudioAd.InstreamAudioAdListener()
    {
        @Override
        public void onLoad(InstreamAudioAd ad)
        {
            // Данные успешно загружены
            // Массив позиций (в секундах), доступных для проигрывания midroll секции
            adPositions = ad.getMidPoints();
        }
         
        ...
    });
     
    // Запускаем загрузку данных
    ad.load();
}
При достижении основным аудио одной из позиций для midroll секции, необходимо вызвать метод startMidroll и передать в него в качестве параметра эту позицию.
// Аудио доигралось до 5-й секунды и для неё есть позиция в массиве adPositions
ad.startMidroll(adPositions[1]);

Доступные свойства рекламного аудио

В методы onBannerStart и onBannerComplete слушателя InstreamAudioAdListener передается экземпляр InstreamAudioAdBanner, содержащий информацию о текущем рекламном аудио, которая может быть использована приложением.
float getDuration();
Длительность текущего рекламного аудио в секундах.
boolean isAllowSeek();
Разрешено ли прокручивать рекламное аудио.
boolean isAllowSkip();
Разрешено ли пропускать рекламное аудио.
boolean isAllowTrackChange();
Разрешено ли переходить к следующему треку.
List<InstreamAdCompanionBanner> getInstreamAdCompanionBanners();
Список баннеров-компаньонов.
String getAdText();
Рекламный текст.

Работа с баннерами-компаньонами

Приложение должно самостоятельно отслеживать показы и клики по баннерам-компаньонам и вызывать методы handleCompanionShow и handleCompanionClick в экземпляре InstreamAudioAd для обработки показа и клика и перехода на рекламируемый сайт или приложение.
private void onCompanionAdShow(InstreamAdCompanionBanner companionBanner)
{
    ad.handleCompanionShow(companionBanner);
}
 
private void onCompanionAdClick(InstreamAdCompanionBanner companionBanner)
{
    // Обработка клика в контексте текущей активности
    ad.handleCompanionClick(companionBanner, context);
 
    // Обработка клика в контексте, который был передан при создании рекламного экземпляра
    // ad.handleCompanionClick(companionBanner);
}

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

У экземпляра InstreamAudioAd доступны следующие методы управления.
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 InstreamAudioAd ad;
 
private void initAd()
{
    // Создаем экземпляр InstreamAudioAd
    ad = new InstreamAudioAd(YOUR_SLOT_ID, this);
    // Получаем экземпляр дополнительных параметров CustomParams
    CustomParams customParams = ad.getCustomParams();
    // Задаем возраст
    customParams.setAge(25);
    // Задаем пол
    customParams.setGender(CustomParams.Gender.MALE);
}

Примеры

Примеры интеграции доступны в нашем демоприложении на Github.
Вам помогла эта статья?
Да
Нет