Начало работы с IMA DAI SDK

IMA SDK упрощают интеграцию мультимедийной рекламы на ваши веб-сайты и приложения. IMA SDK могут запрашивать рекламу с любого рекламного сервера , совместимого с VAST, и управлять воспроизведением рекламы в ваших приложениях. С помощью SDK IMA DAI приложения отправляют потоковый запрос на рекламу и видеоконтент — либо VOD, либо контент в реальном времени. Затем SDK возвращает объединенный видеопоток, так что вам не придется управлять переключением между рекламой и видеоконтентом в вашем приложении.

Выберите решение DAI, которое вас интересует

Полный сервис обслуживания капсул

Полный сервис DAI

В этом руководстве показано, как интегрировать IMA DAI SDK в простое приложение видеоплеера. Если вы хотите просмотреть или проследить за завершенным примером интеграции, загрузите BasicExample с GitHub.

Примечание. IMA DAI SDK для Android поддерживает потоки HLS и DASH.

В этом руководстве объясняется, как настроить exoplayer и IMA DAI SDK для воспроизведения потока HLS. Пример видеоплеера, поддерживающего потоки HLS и DASH, см. в нашем расширенном примере .

Чтобы использовать IMA DAI, у вас должен быть аккаунт Менеджера рекламы 360 Advanced . Если у вас есть учетная запись Менеджера рекламы, обратитесь к менеджеру своего аккаунта за более подробной информацией. Информацию о регистрации в Менеджере рекламы можно найти в Справочном центре Менеджера рекламы .

Ключевой момент: расширение ExoPlayer IMA предлагает упрощенный способ использования IMA DAI на Android. Дополнительные сведения см . в руководстве по расширению ExoPlayer IMA и в ExoPlayerExample на GitHub .

Примечание. Информацию об интеграции с другими платформами или использовании клиентских SDK IMA см. в разделе SDK интерактивной медиарекламы .

Обзор IMA DAI

Реализация IMA DAI включает в себя четыре основных компонента SDK, как показано в этом руководстве:

• StreamDisplayContainer : объект-контейнер, который находится поверх элемента воспроизведения видео и содержит элементы пользовательского интерфейса рекламы.
• AdsLoader : объект, который запрашивает потоки и обрабатывает события, вызванные объектами ответа на запрос потока. Вам следует создать только один экземпляр загрузчика рекламы, который можно будет повторно использовать на протяжении всего срока службы приложения.
• StreamRequest : объект, определяющий запрос потока. Запросы на поток могут относиться как к видео по запросу, так и к прямым трансляциям. В запросах указывается идентификатор контента, а также ключ API или токен аутентификации и другие параметры.
• StreamManager : объект, который обрабатывает потоки динамической вставки рекламы и взаимодействие с серверной частью DAI. Менеджер потоков также обрабатывает отслеживание пингов и пересылает события потока и рекламы издателю.

Предварительные условия

• Android-студия
• Пример приложения видеоплеера для интеграции SDK

Загрузите и запустите пример приложения видеоплеера.

Пример приложения предоставляет работающий видеопроигрыватель, воспроизводящий видео HLS. Используйте это как отправную точку для интеграции возможностей DAI IMA DAI SDK.

1. Загрузите образец приложения видеоплеера и распакуйте его.

2. Запустите Android Studio и выберите «Открыть существующий проект Android Studio» или, если Android Studio уже запущена, выберите «Файл» > «Создать» > «Импортировать проект» . Затем выберите SampleVideoPlayer/build.gradle .

3. Запустите синхронизацию Gradle, выбрав «Инструменты» > «Android» > «Синхронизировать проект с файлами Gradle» .

4. Убедитесь, что приложение проигрывателя компилируется и запускается на физическом устройстве Android или виртуальном устройстве Android с помощью команды «Выполнить» > «Выполнить приложение» . Видеопоток загружается несколько секунд перед воспроизведением. Это нормально.

Совет: Если вы новичок в разработке приложений для Android, ознакомьтесь с учебными пособиями по отладке по USB и использованию виртуальных устройств . Вам нужно сделать одно из этих двух действий, чтобы запустить новое приложение и посмотреть, как оно выглядит.

Изучите образец видеоплеера

Пример видеопроигрывателя пока не содержит кода интеграции IMA DAI SDK. Пример приложения состоит из двух основных частей:

1. samplevideoplayer/SampleVideoPlayer.java : проигрыватель HLS на основе ExoPlayer , который служит основой для интеграции IMA DAI.

2. 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.1'
}

Ключевой момент: на этом этапе ваше приложение должно скомпилироваться и запуститься, хотя вам еще предстоит добавить элементы пользовательского интерфейса или код для запроса и отображения рекламы.

Интегрируйте IMA DAI SDK

1. Создайте новый класс SampleAdsWrapper в пакете videoplayerapp (в app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/ ), чтобы обернуть существующий SampleVideoPlayer и добавить логику, реализующую IMA DAI. Для этого вам необходимо сначала создать AdsLoader , который будет использоваться для запроса рекламы с рекламных серверов.

   Важно. Чтобы уменьшить задержку, вызванную IMA, важно создать AdsLoader сразу после запуска приложения. Это максимально увеличивает время, необходимое IMA для загрузки необходимых ресурсов перед первым запросом Steam. Вам также следует повторно использовать один экземпляр 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());
       }
   }
   

2. Добавьте в 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;
   }
   

3. Вам также понадобится 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;
   }
   

4. Реализуйте необходимые прослушиватели и добавьте поддержку обработки ошибок.

   Обратите внимание на реализацию 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;
   }
   

5. Добавьте код для регистрации.

   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);
       }
   }
   

6. Измените 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);
               }
           });
       }
   ...
   }
   

7. Измените файл макета действия 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 .