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

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

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

Обзор клиентской части IMA

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

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

Предпосылки

Прежде чем начать, вам понадобится Android Studio 3.0 или выше .

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

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

  1. Запустите Android Studio.
  2. Выберите Начать новый проект Android Studio .
  3. На странице «Выберите свой проект» выберите шаблон «Пустая деятельность» .
  4. Нажмите кнопку «Далее» .
  5. На странице «Настройка проекта» дайте проекту имя и выберите Java в качестве языка.
  6. Нажмите кнопку Готово .

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

Сначала в файле build.gradle уровня приложения добавьте импорт расширения в раздел зависимостей. В связи с размером расширения ExoPlayer IMA, реализуйте и включите multidex здесь. Это необходимо для приложений, у которых minSdkVersion установлен на 20 или ниже. Также добавьте новый compileOptions для указания информации о совместимости с версией Java.

apply plugin: 'com.android.application'

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

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

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

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.8.0"
    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"

    implementation 'androidx.multidex:multidex:2.0.1'
}

build.gradle

3. Создайте контейнер пользовательского интерфейса рекламы.

Создайте представление для использования в качестве ExoPlayer PlayerView, создав 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. Импортируйте расширение ExoPlayer IMA.

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

import static android.os.Build.VERSION.SDK_INT;

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 androidx.multidex.MultiDex;
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-адресом тега рекламы.

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

  // 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
@Override
public void onStart() {
  super.onStart();
  if (SDK_INT > 23) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

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

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

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

@Override
protected void onDestroy() {
  adsLoader.release();

  super.onDestroy();
}

MyActivity.java

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