IMA SDK упрощают интеграцию мультимедийной рекламы на ваши веб-сайты и приложения. IMA SDK могут запрашивать рекламу с любого рекламного сервера , совместимого с VAST, и управлять воспроизведением рекламы в ваших приложениях. С помощью SDK IMA DAI приложения отправляют потоковый запрос на рекламу и видеоконтент — либо VOD, либо контент в реальном времени. Затем SDK возвращает объединенный видеопоток, так что вам не придется управлять переключением между рекламой и видеоконтентом в вашем приложении.
Выберите решение DAI, которое вас интересует
Полный сервис DAI
В этом руководстве показано, как интегрировать IMA DAI SDK в простое приложение видеоплеера. Если вы хотите просмотреть или проследить за завершенным примером интеграции, загрузите BasicExample с GitHub.
Обзор IMA DAI
Реализация IMA DAI включает в себя четыре основных компонента SDK, как показано в этом руководстве:
-
StreamDisplayContainer: объект-контейнер, который находится поверх элемента воспроизведения видео и содержит элементы пользовательского интерфейса рекламы. -
AdsLoader: объект, который запрашивает потоки и обрабатывает события, вызванные объектами ответа на запрос потока. Вам следует создать только один экземпляр загрузчика рекламы, который можно будет повторно использовать на протяжении всего срока службы приложения. -
StreamRequest: объект, определяющий запрос потока. Запросы на поток могут относиться как к видео по запросу, так и к прямым трансляциям. В запросах указывается идентификатор контента, а также ключ API или токен аутентификации и другие параметры. -
StreamManager: объект, который обрабатывает потоки динамической вставки рекламы и взаимодействие с серверной частью DAI. Менеджер потоков также обрабатывает отслеживание пингов и пересылает события потока и рекламы издателю.
Предварительные условия
- Android-студия
- Пример приложения видеоплеера для интеграции SDK
Загрузите и запустите пример приложения видеоплеера.
Пример приложения предоставляет работающий видеопроигрыватель, воспроизводящий видео HLS. Используйте это как отправную точку для интеграции возможностей DAI IMA DAI SDK.
Загрузите образец приложения видеоплеера и распакуйте его.
Запустите Android Studio и выберите «Открыть существующий проект Android Studio» или, если Android Studio уже запущена, выберите «Файл» > «Создать» > «Импортировать проект» . Затем выберите
SampleVideoPlayer/build.gradle.Запустите синхронизацию Gradle, выбрав «Инструменты» > «Android» > «Синхронизировать проект с файлами Gradle» .
Убедитесь, что приложение проигрывателя компилируется и запускается на физическом устройстве Android или виртуальном устройстве Android с помощью команды «Выполнить» > «Выполнить приложение» . Загрузка видеопотока перед воспроизведением является нормальным явлением. Это нормально.
Изучите образец видеоплеера
Пример видеопроигрывателя пока не содержит кода интеграции IMA DAI SDK. Пример приложения состоит из двух основных частей:
samplevideoplayer/SampleVideoPlayer.java: проигрыватель HLS на основе ExoPlayer , который служит основой для интеграции IMA DAI.videoplayerapp/MyActivity.java: это действие создает видеоплеер и передает емуContextиSimpleExoPlayerView.
Добавьте IMA DAI SDK в приложение плеера.
Вы также должны включить ссылку на IMA DAI SDK. В Android Studio добавьте следующее в файл build.gradle уровня приложения, расположенный по адресу app/build.gradle :
repositories {
google()
mavenCentral()
}
dependencies {
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'androidx.media3:media3-exoplayer:1.3.1'
implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.35.0'
}
Интегрируйте IMA DAI SDK
Создайте новый класс
SampleAdsWrapperв пакетеvideoplayerapp(вapp/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/), чтобы обернуть существующийSampleVideoPlayerи добавить логику, реализующую IMA DAI. Для этого вам необходимо сначала создатьAdsLoader, который будет использоваться для запроса рекламы с рекламных серверов.videoplayerapp/SampleAdsWrapper.java
package com.google.ads.interactivemedia.v3.samples.videoplayerapp; import android.annotation.TargetApi; import android.content.Context; import android.os.Build; import android.view.ViewGroup; import android.webkit.WebView; import com.google.ads.interactivemedia.v3.api.AdErrorEvent; import com.google.ads.interactivemedia.v3.api.AdEvent; import com.google.ads.interactivemedia.v3.api.AdsLoader; import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent; import com.google.ads.interactivemedia.v3.api.CuePoint; import com.google.ads.interactivemedia.v3.api.ImaSdkFactory; import com.google.ads.interactivemedia.v3.api.ImaSdkSettings; import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer; import com.google.ads.interactivemedia.v3.api.StreamManager; import com.google.ads.interactivemedia.v3.api.StreamRequest; import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate; import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer; import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer; import java.util.ArrayList; import java.util.HashMap; import java.util.List; public class SampleAdsWrapper implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener { // Livestream asset key. private static final String TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA"; // VOD content source and video IDs. private static final String TEST_CONTENT_SOURCE_ID = "2548831"; private static final String TEST_VIDEO_ID = "tears-of-steel"; private static final String PLAYER_TYPE = "DAISamplePlayer"; /** * Log interface, so you can output the log commands to the UI or similar. */ public interface Logger { void log(String logMessage); } private ImaSdkFactory sdkFactory; private AdsLoader adsLoader; private StreamDisplayContainer displayContainer; private StreamManager streamManager; private List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks; private SampleVideoPlayer videoPlayer; private Context context; private ViewGroup adUiContainer; private String fallbackUrl; private Logger logger; public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) { this.videoPlayer = videoPlayer; this.context = context; this.adUiContainer = adUiContainer; sdkFactory = ImaSdkFactory.getInstance(); playerCallbacks = new ArrayList<>(); createAdsLoader(); displayContainer = sdkFactory.createStreamDisplayContainer( this.adUiContainer, videoStreamPlayer ); } private void createAdsLoader() { ImaSdkSettings settings = new ImaSdkSettings(); adsLoader = sdkFactory.createAdsLoader(context); } public void requestAndPlayAds() { adsLoader.addAdErrorListener(this); adsLoader.addAdsLoadedListener(this); adsLoader.requestStream(buildStreamRequest()); } }Добавьте в
AdsLoaderметодbuildStreamRequest(), чтобы он мог запрашивать поток с рекламой. Это либо прямая трансляция с рекламой (установлено по умолчанию), либо поток видео по запросу (VOD), в котором воспроизводится предварительно записанный контент с рекламой. Чтобы включить поток VOD, закомментируйте запрос прямой трансляции и раскомментируйте запрос потока VOD.Для работы с DAI игрок должен передавать события ID3 для прямых трансляций в SDK IMA DAI. В следующем примере кода это делается с помощью метода
callback.onUserTextReceived().videoplayerapp/SampleAdsWrapper.java
private StreamRequest buildStreamRequest() { VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer(); videoPlayer.setSampleVideoPlayerCallback( new SampleVideoPlayer.SampleVideoPlayerCallback() { @Override public void onUserTextReceived(String userText) { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onUserTextReceived(userText); } } @Override public void onSeek(int windowIndex, long positionMs) { // See if you would seek past an ad, and if so, jump back to it. long newSeekPositionMs = positionMs; if (streamManager != null) { CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTime(positionMs / 1000); if (prevCuePoint != null && !prevCuePoint.isPlayed()) { newSeekPositionMs = (long) (prevCuePoint.getStartTime() * 1000); } } videoPlayer.seekTo(windowIndex, newSeekPositionMs); } @Override public void onContentComplete() { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onContentComplete(); } } @Override public void onPause() { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onPause(); } } @Override public void onResume() { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onResume(); } } @Override public void onVolumeChanged(int percentage) { for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) { callback.onVolumeChanged(percentage); } } }); // Livestream request. StreamRequest request = sdkFactory.createLiveStreamRequest( TEST_ASSET_KEY, null, displayContainer); // VOD request. Comment the createLiveStreamRequest() line above and uncomment this // createVodStreamRequest() below to switch from a livestream to a VOD stream. // StreamRequest request = sdkFactory.createVodStreamRequest(TEST_CONTENT_SOURCE_ID, // TEST_VIDEO_ID, null, displayContainer); return request; }Вам также понадобится
VideoStreamPlayerдля воспроизведения потока, поэтому добавьте методcreateVideoStreamPlayer(), который создает анонимный класс, реализующийVideoStreamPlayer.videoplayerapp/SampleAdsWrapper.java
private VideoStreamPlayer createVideoStreamPlayer() { VideoStreamPlayer player = new VideoStreamPlayer() { @Override public void loadUrl(String url, List<HashMap<String, String>> subtitles) { videoPlayer.setStreamUrl(url); videoPlayer.play(); } @Override public void addCallback( VideoStreamPlayerCallback videoStreamPlayerCallback) { playerCallbacks.add(videoStreamPlayerCallback); } @Override public void removeCallback( VideoStreamPlayerCallback videoStreamPlayerCallback) { playerCallbacks.remove(videoStreamPlayerCallback); } @Override public void onAdBreakStarted() { // Disable player controls. videoPlayer.enableControls(false); log("Ad Break Started\n"); } @Override public void onAdBreakEnded() { // Re-enable player controls. videoPlayer.enableControls(true); log("Ad Break Ended\n"); } @Override public VideoProgressUpdate getContentProgress() { return new VideoProgressUpdate(videoPlayer.getCurrentPosition(), videoPlayer.getDuration()); } @Override public int getVolume() { return videoPlayer.getVolume(); } }; return player; }Реализуйте необходимые прослушиватели и добавьте поддержку обработки ошибок.
Обратите внимание на реализацию
AdErrorListener, поскольку она вызывает резервный URL-адрес, если реклама не воспроизводится. Поскольку контент и реклама находятся в одном потоке, вы должны быть готовы вызвать резервный поток, если поток DAI обнаружит ошибку.videoplayerapp/SampleAdsWrapper.java
/** AdErrorListener implementation **/ @Override public void onAdError(AdErrorEvent event) { // play fallback URL. videoPlayer.setStreamUrl(fallbackUrl); videoPlayer.enableControls(true); videoPlayer.play(); } /** AdEventListener implementation **/ @Override public void onAdEvent(AdEvent event) { switch (event.getType()) { case AD_PROGRESS: // Do nothing or else log are filled by these messages. break; default: log(String.format("Event: %s\n", event.getType())); break; } } /** AdsLoadedListener implementation **/ @Override public void onAdsManagerLoaded(AdsManagerLoadedEvent event) { streamManager = event.getStreamManager(); streamManager.addAdErrorListener(this); streamManager.addAdEventListener(this); streamManager.init(); } /** Sets fallback URL in case ads stream fails. **/ void setFallbackUrl(String url) { fallbackUrl = url; }Добавьте код для регистрации.
videoplayerapp/SampleAdsWrapper.java
/** Sets logger for displaying events to screen. Optional. **/ void setLogger(Logger logger) { this.logger = logger; } private void log(String message) { if (logger != null) { logger.log(message); } }Измените
MyActivityвvideoplayerapp, чтобы создать экземпляр и вызватьSampleAdsWrapper.видеоплеерапп/MyActivity.java
import android.view.ViewGroup; import android.widget.ScrollView; ... public class MyActivity extends AppCompatActivity { ... @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_my); View rootView = findViewById(R.id.videoLayout); videoPlayer = new SampleVideoPlayer(rootView.getContext(), (SimpleExoPlayerView) rootView.findViewById(R.id.playerView)); videoPlayer.enableControls(false); final SampleAdsWrapper sampleAdsWrapper = new SampleAdsWrapper(this, videoPlayer, (ViewGroup) rootView.findViewById(R.id.adUiContainer)); sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL); final ScrollView scrollView = (ScrollView) findViewById(R.id.logScroll); final TextView textView = (TextView) findViewById(R.id.logText); sampleAdsWrapper.setLogger(new SampleAdsWrapper.Logger() { @Override public void log(String logMessage) { Log.i(APP_LOG_TAG, logMessage); if (textView != null) { textView.append(logMessage); } if (scrollView != null) { scrollView.post(new Runnable() { @Override public void run() { scrollView.fullScroll(View.FOCUS_DOWN); } }); } } }); playButton = (ImageButton) rootView.findViewById(R.id.playButton); // Set up play button listener to play video then hide play button. playButton.setOnClickListener(new View.OnClickListener() { @Override public void onClick(View view) { sampleAdsWrapper.requestAndPlayAds(); playButton.setVisibility(View.GONE); } }); } ... }Измените файл макета действия
activity_my.xml, добавив элементы пользовательского интерфейса для ведения журнала.res/layout/activity_my.xml
... <TextView android:id="@+id/playerDescription" android:text="@string/video_description" android:textAlignment="center" android:gravity="center_horizontal" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="0.1" android:textSize="@dimen/font_size" /> <!-- UI element for viewing SDK event log --> <ScrollView android:id="@+id/logScroll" android:layout_width="match_parent" android:layout_height="0dp" android:layout_weight="0.5" android:padding="5dp" android:background="#DDDDDD"> <TextView android:id="@+id/logText" android:layout_width="match_parent" android:layout_height="wrap_content"> </TextView> </ScrollView> ...
Поздравляю! Теперь вы запрашиваете и показываете видеорекламу в своем приложении для Android. Для более точной настройки вашей реализации см. Bookmarks , Snapback и документацию по API .
Поиск неисправностей
Если у вас возникли проблемы с воспроизведением видеорекламы, попробуйте загрузить готовый файл BasicExample . Если в BasicExample он работает правильно, то, скорее всего, возникла проблема с кодом интеграции IMA вашего приложения.
Если проблемы по-прежнему возникают, посетите форум IMA SDK .