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

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

Вот некоторые преимущества расширения:

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

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

Поддержка потока расширения ExoPlayer-IMA
	Прямая трансляция	VOD-потоки
ЗОЖ
БРОСАТЬСЯ

Прямые трансляции DASH поддерживаются в ExoPlayer-IMA версии 1.1.0+.

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

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

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

• Android-студия
• AndroidX Media3 ExoPlayer версии 1.0.0 или выше для поддержки DAI.

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

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

• Запустите Android-студию.
• Выберите «Начать новый проект Android Studio» .
• На странице «Выберите проект» выберите шаблон «Нет активности» .
• Нажмите "Далее .

• На странице «Настройка проекта» укажите имя своего проекта и выберите Java в качестве языка.

  Примечание. IMA DAI SDK совместим с Kotlin. Однако пример, рассмотренный в этом руководстве, использует Java.

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

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

Добавьте импорт для расширения в файл build.gradle уровня приложения в разделе dependencies .

Настройте свое приложение и включите multidex . Это необходимо из-за размера расширения и требуется для приложений, для которых minSdkVersion установлено значение Android 4,4W (уровень API 20) или ниже.

Вот пример:

приложение/build.gradle

android {

  ...

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 19
      targetSdkVersion 34
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.1.1'
    implementation 'androidx.media3:media3-exoplayer:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-hls:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-dash:1.1.1'

    // Adding the ExoPlayer IMA extension for ads will also include the IMA
    // SDK as a dependency.
    implementation 'androidx.media3:media3-exoplayer-ima:1.1.1'
}

Добавьте разрешения пользователя, необходимые IMA SDK для запроса рекламы:

приложение/src/main/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.project name">

    <!-- Required permissions for the IMA SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

Добавить декларации о намерениях

Если ваше приложение предназначено для Android 11 (уровень API 30) или выше, текущая и последняя версии IMA SDK требуют явного заявления о намерении для открытия веб-ссылок. Добавьте следующий фрагмент в файл манифеста вашего приложения, чтобы включить переходы по объявлениям (пользователи нажимают кнопку «Подробнее» ).

Примечание. Будущие версии IMA SDK будут автоматически включать эти объявления и объединяться с файлом манифеста вашего приложения.

  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.example.project name">

      ...

    </application>

    <queries>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="https" />
      </intent>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="http" />
      </intent>
    </queries>
  </manifest>

Настройте пользовательский интерфейс ExoPlayer

Создайте объект PlayerView , который будет использоваться ExoPlayer.

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

Вот пример:

приложение/src/main/res/layout/activity_my.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:background="@android:color/black"
    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:layout_width="match_parent"
        android:layout_height="match_parent" />

</LinearLayout>

Добавьте параметры вашего потока

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

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

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

Добавьте инструкции импорта для расширения ExoPlayer.

Добавьте следующие частные переменные в MyActivity.java :

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

Добавьте ключ ресурса потока HLS Big Buck Bunny (Live) для тестирования с этим потоком. Дополнительные потоки доступны для тестирования на странице образцов потоков IMA .

Создайте константу KEY_ADS_LOADER_STATE для сохранения и получения состояния AdsLoader .

Вот пример:

app/src/main/java/com/example/ project name /MyActivity.java

import static androidx.media3.common.C.CONTENT_TYPE_HLS;

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.annotation.OptIn;
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.exoplayer.util.EventLogger;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

}

Создайте adsLoader .

Перезапишите метод onCreate , чтобы найти PlayerView и проверить наличие сохраненного AdsLoader.State , который можно использовать при инициализации adsLoader .

Кроме того, включите multidex, если этого требуют количество методов вашего приложения и minSdkVersion (как описано в шаге 2 ).

Вот пример:

app/src/main/java/com/example/ project name /MyActivity.java

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

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

    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.CREATOR.fromBundle(
                adsLoaderStateBundle);
      }
    }
  }

}

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

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

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

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

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

Вот пример:

app/src/main/java/com/example/ project name /MyActivity.java

public class MyActivity extends Activity {

  ...

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

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

    return adsLoaderBuilder.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 an ExoPlayer and set it as the player for content and ads.
    player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
    playerView.setPlayer(player);
    adsLoader.setPlayer(player);

    // Build an IMA SSAI media item to prepare the player with.
    Uri ssaiLiveUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setAssetKey(SAMPLE_ASSET_KEY)
            .setFormat(CONTENT_TYPE_HLS) // Use CONTENT_TYPE_DASH for dash streams.
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiLiveUri);

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

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

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

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

app/src/main/java/com/example/ project name /MyActivity.java

public class MyActivity extends Activity {

  ...

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

Обработка событий игрока

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

Для поддержки Android SDK версии 24+:

• onStart()
• onStop()

Для поддержки версий Android SDK ниже 24: - onResume() - onPause()

onStart() и onResume() сопоставляются с playerView.onResume() , а onStop() и onPause() сопоставляются с playerView.onPause() .

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

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

app/src/main/java/com/example/ project name /MyActivity.java

public class MyActivity extends Activity {

  ...

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

  ...

}

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

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

1. Добавьте CMS ID и Video ID для тестового потока VOD.
2. Создайте URI VOD SSAI с помощью ImaServerSideAdInsertionUriBuilder() .
3. Используйте этот новый URI в качестве медиа-элемента вашего проигрывателя.

app/src/main/java/com/example/ project name /MyActivity.java

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 SAMPLE_CMS_ID = "2528370";
  private static final String SAMPLE_VIDEO_ID = "tears-of-steel";

  ...

  private void initializePlayer() {

     ...

    Uri ssaiVodUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setContentSourceId(SAMPLE_CMS_ID)
            .setVideoId(SAMPLE_VIDEO_ID)
            .setFormat(CONTENT_TYPE_HLS)
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiVodUri);

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

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