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

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

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

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

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

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

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

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

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

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

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

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

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

приложение/build.gradle
android {
    namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdkVersion 34

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
  }

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

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.3.1'
    implementation 'androidx.media3:media3-exoplayer:1.3.1'
    implementation 'androidx.media3:media3-exoplayer-ima:1.3.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 требуют явного заявления о намерении для открытия веб-ссылок. Добавьте следующий фрагмент в файл манифеста вашего приложения, чтобы включить переходы по объявлениям (пользователи нажимают кнопку «Подробнее» ).
  <?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>

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

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

приложение/src/main/res/layout/activity_main.xml
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.media3.ui.PlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

</LinearLayout>

4. Добавьте URL-адрес контента и URL-адрес тега объявления для запроса объявлений.

Добавьте записи в strings.xml для хранения URL-адреса вашего контента и URL-адреса тега объявления VAST.

приложение/src/main/res/values/strings.xml
<resources>
    <string name="app_name">Your_Project_Name</string>
    <string name="content_url"><![CDATA[https://storage.googleapis.com/gvabox/media/samples/stock.mp4]]></string>
    <string name="ad_tag_url"><![CDATA[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&impl=s&correlator=]]></string>

</resources>

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

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

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

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
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.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

public class MainActivity extends Activity {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

}

6. Создайте adsLoader .

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

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

...

public class MainActivity extends Activity {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

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

    playerView = findViewById(R.id.player_view);

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

  public AdEvent.AdEventListener buildAdEventListener() {

    AdEvent.AdEventListener imaAdEventListener = event -> {
      AdEvent.AdEventType eventType = event.getType();
      // Log IMA events for debugging.
      // The ExoPlayer IMA extension already handles IMA events and does not need anything
      // additional here to function.
    };

    return imaAdEventListener;
  }

}

7. Инициализируйте и отпустите плеер.

Добавьте методы для инициализации и освобождения проигрывателя. В методе инициализации создайте SimpleExoPlayer . Затем создайте AdsMediaSource и установите его для проигрывателя.

app/src/main/java/com/example/ project name /MainActivity.java
public class MainActivity extends Activity {

  ...

  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(getString(R.string.content_url));
    Uri adTagUri = Uri.parse(getString(R.string.ad_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);
  }
}

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

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

  • onStart
  • onResume
  • onStop
  • onPause
  • onDestroy
app/src/main/java/com/example/ project name /MainActivity.java
public class MainActivity extends Activity {

  private PlayerView playerView;
  private SimpleExoPlayer player;
  private ImaAdsLoader adsLoader;

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

      playerView = findViewById(R.id.player_view);

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

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

  ...

}

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