Exoplayer IMA 扩展程序使用入门

借助 IMA SDK，您可以轻松地将多媒体广告集成到网站和应用中。IMA SDK 可以从任何 符合 VAST 标准的广告服务器请求广告，并在您的应用中管理广告播放。借助 IMA 客户端 SDK，您可以继续控制内容视频播放，而 SDK 则负责处理广告播放。广告在位于应用内容视频播放器顶部的单独视频播放器中播放。

本指南演示了如何使用 ExoPlayer IMA 扩展程序将 IMA SDK 集成到空的 Android Studio 项目中。如果您想查看或跟随完成的示例集成，请从 GitHub 下载 BasicExample。

注意：如需了解如何与其他平台集成，或如何使用 IMA DAI SDK，请参阅 互动式媒体广告 SDK。

IMA 客户端概览

实现 IMA 客户端涉及四个主要 SDK 组件，本指南将对此进行演示：

• AdDisplayContainer：一个容器对象，用于指定 IMA 呈现广告界面元素和衡量可见率的位置，包括 Active View 和 Open Measurement。
• AdsLoader： 一个用于请求广告并处理广告请求响应中的事件的对象。您只需实例化一个广告加载程序，该加载程序可在整个应用生命周期内重复使用。
• AdsRequest： 用于定义广告请求的对象。广告请求会指定 VAST 广告代码的网址以及其他参数（例如广告尺寸）。
• AdsManager： 一个包含广告请求响应、控制广告播放并监听 SDK 触发的广告事件的对象。

注意：由于 ExoPlayer IMA 扩展程序在本指南中封装了 IMA SDK，因此 AdsRequest 和 AdsManager 都会使用，但不会显式调用。

前提条件

开始前，您需要使用 Android Studio 3.0 或更高版本。

1. 创建新的 Android Studio 项目

如需创建 Android Studio 项目，请完成以下步骤：

1. 启动 Android Studio。
2. 选择 Start a new Android Studio project。
3. 在 Choose your project 页面中，选择 Empty Activity 模板。
4. 点击下一步。
5. 在配置项目页面中，为项目命名，然后选择 Java 作为语言。
   注意：IMA SDK 与 Kotlin 兼容。不过，本指南中介绍的示例使用的是 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. 创建广告界面容器

通过创建 androidx.media3.ui.PlayerView 来创建要用作 ExoPlayer 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 语句：

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

然后，通过添加 PlayerView、ExoPlayer、ImaAdsLoader 和 ImaSdkSettings 的私有变量，更新 MainActivity 类以扩展 Activity：

/** 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 对象。

重要提示：为了缩短 IMA 加载时间，请在应用生命周期中尽早调用 ImaSdkFactory.initialize() 方法。尽早调用该方法可最大限度地延长 IMA 在发出首个广告请求之前加载必要资源的时间。ImaSdkFactory.initialize() 方法调用接受 ImaSdkSettings 实例。请务必在此处和创建 AdsLoader 实例时使用相同的设置值。此示例使用 getImaSdkSettings() 辅助方法来确保设置值相同。如需了解详情，请参阅优化 IMA 加载时间指南。

@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

注意： 示例代码针对 Android SDK 版本 24 及更高版本使用 onStart/onStop，针对低于 24 的版本使用 onResume/onPause。

@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 上的示例。