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

IMA SDK позволяет легко интегрировать мультимедийные объявления на сайты и в приложения. IMA SDK могут запрашивать объявления у любого совместимого с VAST сервера объявлений и управлять воспроизведением рекламы в ваших приложениях. Клиентские IMA SDK позволяют управлять воспроизведением видеоконтента, а воспроизведение рекламы берет на себя SDK. Объявления показываются в отдельном видеопроигрывателе, расположенном поверх видеопроигрывателя контента приложения.

В этом руководстве рассказывается, как интегрировать IMA SDK в пустой проект Android Studio с помощью расширения IMA для ExoPlayer. Если вы хотите посмотреть или повторить пример интеграции, скачайте BasicExample с GitHub.

Примечание. Информацию об интеграции с другими платформами или об использовании IMA DAI SDK можно найти в статье Interactive Media Ads SDK.

Общие сведения о реализации IMA на стороне клиента

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

• AdDisplayContainer – объект-контейнер, который указывает, где IMA будет отрисовывать элементы интерфейса рекламы и отслеживать видимость, в том числе с помощью Active View и Open Measurement.
• AdsLoader: объект, который запрашивает объявления и обрабатывает события из ответов на запросы объявлений. В приложении должен быть только один загрузчик объявлений, который можно использовать многократно.
• AdsRequest – объект, определяющий запрос объявлений. В запросах объявлений указывается URL тега объявления VAST, а также дополнительные параметры, например размеры объявления.
• AdsManager: объект, который содержит ответ на запрос объявлений, управляет воспроизведением объявлений и отслеживает события объявлений, активируемые SDK.

Примечание. Поскольку расширение ExoPlayer IMA включает в себя IMA SDK, в этом руководстве используются как AdsRequest, так и AdsManager, но они не вызываются явным образом.

Требования

Для начала работы вам потребуется Android Studio 3.0 или более поздней версии.

1. Как создать проект Android Studio

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

1. Запустите Android Studio.
2. Выберите Начать новый проект Android Studio.
3. На странице Choose your project (Выбор проекта) выберите шаблон Empty Activity (Пустой объект activity).
4. Нажмите Далее.
5. На странице Настройте проект укажите название проекта и выберите язык Java.
   Примечание. IMA SDK совместима с Kotlin. Однако в примере, приведенном в этом руководстве, используется Java.
6. Нажмите Готово.

2. Как добавить в проект расширение ExoPlayer IMA

Сначала в файле build.gradle на уровне приложения добавьте импорт расширения в раздел зависимостей. Также добавьте новый элемент compileOptions, чтобы указать информацию о совместимости с версией Java.

apply plugin: 'com.android.application'

android {
    namespace = 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdk = 36

    compileOptions {
        // Required by IMA SDK v3.37.0+
        coreLibraryDesugaringEnabled = true

        // Java 17 required by Gradle 8+
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    defaultConfig {
        applicationId = "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
        minSdkVersion(24)
        targetSdkVersion(36)
        versionCode = 1
        versionName = "1.0"
    }
    buildTypes {
        release {
            minifyEnabled = true
            proguardFiles(getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro')
        }
    }
}

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.11.0"
    coreLibraryDesugaring('com.android.tools:desugar_jdk_libs:2.1.5')
    implementation("androidx.media3:media3-ui:$media3_version")
    implementation("androidx.media3:media3-exoplayer:$media3_version")

    // The library adds the IMA ExoPlayer integration for ads.
    implementation("androidx.media3:media3-exoplayer-ima:$media3_version")
}
build.gradle

3. Создайте контейнер для интерфейса объявления

Создайте представление, которое будет использоваться в качестве PlayerView для ExoPlayer, создав androidx.media3.ui.PlayerView. Также измените androidx.constraintlayout.widget.ConstraintLayout на LinearLayout.

<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: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

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

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

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.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
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;
MyActivity.java

Затем обновите класс MainActivity, чтобы расширить Activity, добавив частные переменные для PlayerView, ExoPlayer, ImaAdsLoader и ImaSdkSettings:

/** Main Activity. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String SAMPLE_VIDEO_URL =
      "https://storage.googleapis.com/gvabox/media/samples/stock.mp4";
  private static final String SAMPLE_VAST_TAG_URL =
      "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/"
          + "single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90"
          + "&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&correlator=";
  private static final String LOG_TAG = "ImaExoPlayerExample";

  private PlayerView playerView;
  private TextView logText;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;
  private ImaSdkSettings imaSdkSettings;
MyActivity.java

5. Как создать экземпляр adsLoader

Переопределите метод onCreate и добавьте необходимые назначения переменных, чтобы создать новый объект adsLoader с URL тега объявления.

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

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

  // Create an AdsLoader.
  adsLoader =
      new ImaAdsLoader.Builder(/* context= */ this)
          .setAdEventListener(buildAdEventListener())
          .setImaSdkSettings(getImaSdkSettings())
          .build();
}
MyActivity.java

Создайте метод buildAdEventListener(), который будет возвращать объект AdEventListener для регистрации событий IMA в целях отладки. Расширение ExoPlayer IMA уже обрабатывает события IMA и не требует дополнительных действий.

public AdEvent.AdEventListener buildAdEventListener() {
  logText = findViewById(R.id.logText);
  logText.setMovementMethod(new ScrollingMovementMethod());

  return event -> {
    AdEvent.AdEventType eventType = event.getType();
    if (eventType == AdEvent.AdEventType.AD_PROGRESS) {
      return;
    }
    String log = "IMA event: " + eventType;
    if (logText != null) {
      logText.append(log + "\n");
    }
    Log.i(LOG_TAG, log);
  };
}
MyActivity.java

Создайте вспомогательный метод getImaSdkSettings(), который будет возвращать объект ImaSdkSettings, чтобы задать настройки IMA SDK:

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

6. Инициализация и освобождение проигрывателя

Добавьте методы для инициализации и освобождения проигрывателя. В методе initializePlayer() создайте ExoPlayer. Затем создайте объект AdsMediaSource и задайте его для проигрывателя:

private void releasePlayer() {
  adsLoader.setPlayer(null);
  playerView.setPlayer(null);
  player.release();
  player = null;
}

private void initializePlayer() {
  // Set up the factory for media sources, passing the ads loader and ad view providers.
  DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

  MediaSource.Factory mediaSourceFactory =
      new DefaultMediaSourceFactory(dataSourceFactory)
          .setLocalAdInsertionComponents(unusedAdTagUri -> adsLoader, playerView);

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

  // Create the MediaItem to play, specifying the content URI and ad tag URI.
  Uri contentUri = Uri.parse(SAMPLE_VIDEO_URL);
  Uri adTagUri = Uri.parse(SAMPLE_VAST_TAG_URL);
  MediaItem mediaItem =
      new MediaItem.Builder()
          .setUri(contentUri)
          .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
          .build();

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

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

7. Как обрабатывать события игрока

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

• onStart
• onResume
• onStop
• onPause
• onDestroy

Примечание. В примере кода используется onStart/onStop для Android SDK версии 24 и выше и onResume/onPause для более ранних версий.

@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
protected void onDestroy() {
  adsLoader.release();

  super.onDestroy();
}
MyActivity.java

Теперь вы можете запрашивать и показывать объявления с помощью IMA SDK. Чтобы узнать больше о дополнительных функциях, ознакомьтесь с другими руководствами или примерами на GitHub.