Начните работу с расширением ExoPlayer IMA

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

Ниже перечислены преимущества расширения:

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

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

Поддержка потоковой передачи расширения ExoPlayer-IMA
	Прямая трансляция	Видеопотоки
ХЛС
БРОСАТЬСЯ

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

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

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

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

• Android Studio
• Для поддержки DAI используется AndroidX Media3 ExoPlayer версии 1.0.0 или более поздней.

Создайте новый проект Android Studio.

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

1. Запустите Android Studio.
2. Выберите «Создать новый проект Android Studio» .
3. На странице «Выберите свой проект» выберите шаблон «Без активности» .
4. Нажмите «Далее» .
5. На странице «Настройка проекта» задайте имя проекта и выберите Java в качестве языка. Примечание: SDK IMA DAI работает с Kotlin, но в этом руководстве используются примеры на Java.

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

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

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

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

   dependencies {
       def media3_version = "1.8.0"
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
       implementation 'androidx.appcompat:appcompat:1.7.1'
       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. Добавьте разрешения пользователя, необходимые SDK IMA DAI для запроса рекламы:

   <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 можно найти на странице с примерами, чтобы протестировать свой проект. Чтобы настроить собственные потоки, см. раздел «Менеджер рекламы» на сайте DAI .

На этом шаге настраивается прямая трансляция. Расширение ExoPlayer IMA также поддерживает потоки DAI VOD. Чтобы узнать, какие изменения необходимы вашему приложению для потоков VOD, см. шаг для потоков видео по запросу (VOD) .

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

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.common.util.Util;
   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 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)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

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

• Google Ad Manager DAI — это пример SSAI.
• Расширение ExoPlayer IMA, описанное в этом руководстве, работает исключительно с Ad Manager DAI. Расширение ExoPlayer IMA также поддерживает различные решения SSAI.

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

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

• Установите для ссылок на игрока значение 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()

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

• onResume()
• onPause()

Методы onStart() и onResume() соответствуют методу playerView.onResume() , а onStop() и onPause() соответствуют методу playerView.onPause() .

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

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

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

@Override
public void onResume() {
  super.onResume();
  if (Util.SDK_INT <= 23 || player == null) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

@Override
public void onPause() {
  super.onPause();
  if (Util.SDK_INT <= 23) {
    if (playerView != null) {
      playerView.onPause();
    }
    releasePlayer();
  }
}

@Override
public void onStop() {
  super.onStop();
  if (Util.SDK_INT > 23) {
    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

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

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

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

2. Создайте URI для SSAI VOD, используя метод 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)
         .setAdTagParameters(adTagParams)
         .build();
   }
   MyActivity.java
   

3. Установите новый URI потока VOD в качестве медиафайла вашего плеера, используя метод MediaItem.fromUri() .

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