Как начать работу с расширением IMA для ExoPlayer

ExoPlayer – это медиапроигрыватель для Android. В этом руководстве рассказывается, как использовать расширение ExoPlayer IMA. Это расширение использует IMA DAI SDK для запроса и воспроизведения медиапотоков с рекламой и контентом.

Преимущества расширения:

• Упрощает код, необходимый для интеграции функций IMA.
• Сокращает время, необходимое для перехода на новые версии IMA.

Расширение ExoPlayer IMA поддерживает протоколы потоковой передачи HLS и DASH. Вот краткое описание:

Поддержка потоков в расширении ExoPlayer-IMA
	Прямая трансляция	Трансляции видео по запросу
HLS;
DASH

ExoPlayer-IMA версии 1.1.0 и более поздних поддерживает трансляции DASH.

В этом руководстве используется руководство по ExoPlayer, которое поможет вам создать полноценное приложение и интегрировать расширение. Полный пример приложения можно найти в ExoPlayerExample на GitHub.

Важно! Для работы расширения IMA ExoPlayer требуется ExoPlayer. Если вы предпочитаете другой проигрыватель, следуйте руководству по началу работы, чтобы интегрировать IMA DAI SDK в свое приложение.

Требования

• Android Studio
• AndroidX Media3 ExoPlayer версии 1.0.0 или более поздней для поддержки динамической вставки объявлений.

Создайте проект Android Studio

Чтобы создать проект Android Studio, выполните следующие действия:

1. Запустите Android Studio.
2. Выберите Start a new Android Studio project (Создать проект Android Studio).
3. На странице Choose your project (Выбор проекта) выберите шаблон No Activity (Без действий).
4. Нажмите Далее.
5. На странице Configure your project (Настройка проекта) укажите название проекта и выберите язык Java. Примечание. IMA DAI SDK работает с Kotlin, но в этом руководстве используются примеры на Java.

• Нажмите Готово.

Добавьте расширение ExoPlayer IMA в проект

Чтобы добавить расширение ExoPlayer IMA, выполните следующие действия:

1. Включите следующие импорты в раздел dependencies файла build.gradle вашего приложения:

   dependencies {
       def media3_version = "1.11.0"
       coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.21"))
       implementation("androidx.appcompat:appcompat:1.8.0")
       implementation("androidx.media3:media3-ui:$media3_version")
       implementation("androidx.media3:media3-exoplayer:$media3_version")
       implementation("androidx.media3:media3-exoplayer-hls:$media3_version")
       implementation("androidx.media3:media3-exoplayer-dash:$media3_version")
   
       // The library adds the IMA ExoPlayer integration for ads.
       implementation("androidx.media3:media3-exoplayer-ima:$media3_version")
   }
   build.gradle
   

2. Добавьте разрешения пользователя, которые нужны IMA DAI SDK для запроса объявлений:

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   AndroidManifest.xml
   

Настройка интерфейса ExoPlayer

Чтобы настроить интерфейс ExoPlayer, выполните следующие действия:

1. Создайте объект PlayerView для ExoPlayer.

2. Измените представление androidx.constraintlayout.widget.ConstraintLayout на LinearLayout, как рекомендуется в расширении ExoPlayer IMA:

   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools"
       android:id="@+id/container"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       android:orientation="vertical"
       tools:context=".MyActivity"
       tools:ignore="MergeRootFrame">
   
       <androidx.media3.ui.PlayerView
           android:id="@+id/player_view"
           android:fitsSystemWindows="true"
           android:layout_width="match_parent"
           android:layout_height="wrap_content" />
   
       <!-- UI element for viewing SDK event log -->
       <TextView
           android:id="@+id/logText"
           android:gravity="bottom"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:maxLines="100"
           android:scrollbars="vertical"
           android:textSize="@dimen/font_size">
       </TextView>
   
   </LinearLayout>
   activity_my.xml
   

Добавьте параметры трансляции

На странице с примерами потоков IMA вы найдете примеры объектов потоков, которые можно использовать для тестирования проекта. Чтобы настроить собственные трансляции, ознакомьтесь с разделом Справочного центра Менеджера рекламы, посвященным динамической вставке объявлений.

На этом шаге настраивается прямая трансляция. Расширение ExoPlayer IMA также поддерживает трансляции видео по запросу с динамической вставкой объявлений. Чтобы узнать, какие изменения нужно внести в приложение для поддержки видео по запросу, ознакомьтесь с инструкциями для видео по запросу.

Импортируйте расширение IMA для ExoPlayer

1. Добавьте следующие операторы импорта для расширения ExoPlayer:

   import static androidx.media3.common.C.CONTENT_TYPE_HLS;
   
   import android.annotation.SuppressLint;
   import android.app.Activity;
   import android.net.Uri;
   import android.os.Bundle;
   import android.text.method.ScrollingMovementMethod;
   import android.util.Log;
   import android.widget.TextView;
   import androidx.media3.common.MediaItem;
   import androidx.media3.datasource.DataSource;
   import androidx.media3.datasource.DefaultDataSource;
   import androidx.media3.exoplayer.ExoPlayer;
   import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionMediaSource;
   import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder;
   import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
   import androidx.media3.ui.PlayerView;
   import com.google.ads.interactivemedia.v3.api.AdEvent;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
   import java.util.HashMap;
   import java.util.Map;
   MyActivity.java
   

2. В MyActivity.java добавьте следующие закрытые переменные:

   • PlayerView
   • ExoPlayer
   • ImaServerSideAdInsertionMediaSource.AdsLoader
   • ImaServerSideAdInsertionMediaSource.AdsLoader.State

   Чтобы выполнить тестирование с помощью потока HLS Big Buck Bunny (Live), добавьте его ключ объекта. Другие потоки для тестирования можно найти на странице с примерами потоков IMA.

3. Создайте константу KEY_ADS_LOADER_STATE, чтобы сохранять и получать состояние AdsLoader:

   /** Main Activity. */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   public class MyActivity extends Activity {
   
     private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
     private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
     private static final String LOG_TAG = "ImaExoPlayerExample";
     private static final String NETWORK_CODE = "21775744923";
   
     private PlayerView playerView;
     private TextView logText;
     private ExoPlayer player;
     private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
     private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;
     private ImaSdkSettings imaSdkSettings;
   MyActivity.java
   

Создайте экземпляр adsLoader

Переопределите метод onCreate. Найдите в нем PlayerView и проверьте, есть ли там сохраненный AdsLoader.State. Вы можете использовать это состояние при инициализации объекта adsLoader.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_my);

  // Initialize the IMA SDK as early as possible when the app starts. If your app already
  // overrides Application.onCreate(), call this method inside the onCreate() method.
  // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
  ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());

  playerView = findViewById(R.id.player_view);

  // Checks if there is a saved AdsLoader state to be used later when initiating the AdsLoader.
  if (savedInstanceState != null) {
    Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE);
    if (adsLoaderStateBundle != null) {
      adsLoaderState =
          ImaServerSideAdInsertionMediaSource.AdsLoader.State.fromBundle(adsLoaderStateBundle);
    }
  }
}

private ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    // Set any IMA SDK settings here.
  }
  return imaSdkSettings;
}
MyActivity.java

Важно! Чтобы сократить время загрузки IMA, вызывайте метод ImaSdkFactory.initialize() как можно раньше в жизненном цикле приложения. Ранний вызов метода позволяет IMA загрузить необходимые ресурсы до первого запроса потока. Вызов метода ImaSdkFactory.initialize() принимает экземпляр ImaSdkSettings. Убедитесь, что вы используете те же значения настроек, что и при создании экземпляра AdsLoader. В этом примере используется вспомогательный метод getImaSdkSettings(), чтобы значения настроек были одинаковыми. Подробную информацию вы найдете в руководстве по оптимизации времени загрузки IMA.

Добавьте методы для инициализации проигрывателя

Добавьте метод для инициализации проигрывателя. Этот метод должен выполнять следующие действия:

• Создайте экземпляр AdsLoader.
• Создайте ExoPlayer.
• Создайте объект MediaItem, используя ключ объекта трансляции.
• Задайте MediaItem для проигрывателя.

// Create a server side ad insertion (SSAI) AdsLoader.
private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
      new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

  // Attempts to set the AdsLoader state if available from a previous session.
  if (adsLoaderState != null) {
    adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
  }

  return adsLoaderBuilder
      .setAdEventListener(buildAdEventListener())
      .setImaSdkSettings(getImaSdkSettings())
      .build();
}

private void initializePlayer() {
  adsLoader = createAdsLoader();

  // Set up the factory for media sources, passing the ads loader.
  DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

  DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory);

  // MediaSource.Factory to create the ad sources for the current player.
  ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
      new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory);

  // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory.
  // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server
  // side inserted ad streams.
  mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);

  // Create a SimpleExoPlayer and set it as the player for content and ads.
  player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
  playerView.setPlayer(player);
  adsLoader.setPlayer(player);

  // Create the MediaItem to play, specifying the stream URI.
  Uri ssaiUri = buildLiveStreamUri(SAMPLE_ASSET_KEY, CONTENT_TYPE_HLS);
  MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiUri);

  // Prepare the content and ad to be played with the ExoPlayer.
  player.setMediaItem(ssaiMediaItem);
  player.prepare();

  // Set PlayWhenReady. If true, content and ads will autoplay.
  player.setPlayWhenReady(false);
}

/**
 * Builds an IMA SSAI live stream URI for the given asset key and format.
 *
 * @param assetKey The asset key of the live stream.
 * @param format The format of the live stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the live stream.
 */
public Uri buildLiveStreamUri(String assetKey, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setAssetKey(assetKey)
      .setFormat(format)
      .setNetworkCode(NETWORK_CODE)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

Примечание. В этом разделе используются методы, названия которых относятся к концепциям вставки объявлений на стороне сервера (SSAI).

• Примером такой технологии является динамическая вставка объявлений в Google Менеджере рекламы .
• Расширение ExoPlayer IMA, описанное в этом руководстве, работает только с динамической вставкой объявлений в Менеджере рекламы. Расширение ExoPlayer IMA также поддерживает различные решения для вставки объявлений на стороне сервера.

Добавь метод для освобождения проигрывателя

Добавьте метод для освобождения проигрывателя. Этот метод должен последовательно выполнять следующие действия:

• Установите для ссылок на проигрыватель значение null и освободите ресурсы проигрывателя.
• Отменить бронирование комнаты "adsLoader".

private void releasePlayer() {
  // Set the player references to null and release the player's resources.
  playerView.setPlayer(null);
  player.release();
  player = null;

  // Release the adsLoader state so that it can be initiated again.
  adsLoaderState = adsLoader.release();
}
MyActivity.java

Обработка событий проигрывателя

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

Для Android API уровня 24 и более поздних версий используйте следующие методы:

• onStart()
• onStop()

Для уровней API Android ниже 24 используйте следующие методы:

• onResume()
• onPause()

Методы onStart() и onResume() сопоставляются с playerView.onResume(), а onStop() и onPause() – с playerView.onPause().

Важно! Этот пример поддерживает Android SDK версии 24 и более ранних. Используйте onStart()/onStop() для Android SDK версии 24 и выше, а onResume()/onPause() – для более ранних версий.

На этом этапе также используется событие onSaveInstanceState(), чтобы сохранить adsLoaderState.

@Override
public void onStart() {
  super.onStart();
  initializePlayer();
  if (playerView != null) {
    playerView.onResume();
  }
}

@Override
public void onResume() {
  super.onResume();
  if (player == null) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

@Override
public void onPause() {
  super.onPause();
}

@Override
public void onStop() {
  super.onStop();
  if (playerView != null) {
    playerView.onPause();
  }
  releasePlayer();
}

@Override
public void onSaveInstanceState(Bundle outState) {
  // Attempts to save the AdsLoader state to handle app backgrounding.
  if (adsLoaderState != null) {
    outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle());
  }
}
MyActivity.java

Настройка трансляции видео по запросу (необязательно)

Если в вашем приложении нужно воспроизводить видео по запросу с рекламой, выполните следующие действия:

1. Добавьте CMS ID и Video ID для видео по запросу. Для тестирования используйте следующие параметры потока:
   • Идентификатор CMS: "2548831"
   • Идентификатор видео: "tears-of-steel"

2. Создайте URI для видео по запросу с вставкой объявлений на стороне сервера, используя метод ImaServerSideAdInsertionUriBuilder():

   /**
    * Builds an IMA SSAI VOD stream URI for the given CMS ID, video ID, and format.
    *
    * @param cmsId The CMS ID of the VOD stream.
    * @param videoId The video ID of the VOD stream.
    * @param format The format of the VOD stream request, either {@code CONTENT_TYPE_HLS} or {@code
    *     CONTENT_TYPE_DASH}.
    * @return The URI of the VOD stream.
    */
   public Uri buildVodStreamUri(String cmsId, String videoId, int format) {
     Map<String, String> adTagParams = new HashMap<String, String>();
     // Update the adTagParams map with any parameters.
     // For more information, see https://support.google.com/admanager/answer/7320899
   
     return new ImaServerSideAdInsertionUriBuilder()
         .setContentSourceId(cmsId)
         .setVideoId(videoId)
         .setFormat(format)
         .setNetworkCode(NETWORK_CODE)
         .setAdTagParameters(adTagParams)
         .build();
   }
   MyActivity.java
   

3. Укажите новый URI потока видео по запросу в качестве мультимедийного объекта проигрывателя с помощью метода MediaItem.fromUri().

Если все в порядке, вы можете запросить и воспроизвести медиапоток с помощью расширения ExoPlayer IMA. Полный пример кода можно найти в примерах динамической вставки объявлений для Android на GitHub.