本頁面由 Cloud Translation API 翻譯而成。

開始使用 Exoplayer IMA 擴充功能

IMA SDK 可讓您輕鬆將多媒體廣告整合至您的網站和應用程式。IMA SDK 可以向任何與 VAST 相容的廣告伺服器，並管理您應用程式中的廣告播放方式。使用 IMA 用戶端 SDK 您能掌控內容影片播放，而 SDK 會處理廣告播放。廣告在獨立影片播放器位於應用程式內容影片播放器上方。

本指南說明如何使用 ExoPlayer IMA 擴充功能。如要查看或按照已完成的整合範例操作，請下載 GitHub 的 BasicExample。

IMA 用戶端總覽

導入 IMA 用戶端需要四個主要的 SDK 元件，如本例所示指南：

AdDisplayContainer: 廣告顯示位置的容器物件。
AdsLoader: 這個物件會請求廣告，以及處理廣告請求回應中的事件。除了將一個廣告載入器執行個體化，以便在應用程式生命週期中重複使用。
AdsRequest: 定義廣告請求的物件。廣告請求會指定 VAST 廣告代碼的網址，以及額外參數，例如廣告尺寸。
AdsManager: 包含回應廣告請求、控制廣告播放以及監聽廣告的物件 SDK 觸發的事件。

，瞭解如何調查及移除這項存取權。

注意：由於 ExoPlayer IMA 擴充功能會納入本指南中的 IMA SDK，同時使用 AdsRequest 和 AdsManager，但未使用。

必要條件

開始之前，您必須備妥 Android Studio 3.0 以上版本。

1. 建立新的 Android Studio 專案

如要建立 Android Studio 專案，請完成下列步驟：

啟動 Android Studio。
選取「Start a new Android Studio project」(啟動新的 Android Studio 專案)。
在「Choose your project」(選擇專案) 頁面中，選取「Empty Activity」(空白活動) 範本。
點選「下一步」。
在「Configure your project」頁面中為專案命名，然後選取「Java」做為語言。
注意：IMA SDK 與 Kotlin 相容。不過，本指南中的範例使用的是 Java。
按一下 [完成]。

2. 在專案中新增 ExoPlayer IMA 擴充功能

首先，請在應用程式層級的 build.gradle 檔案中，將副檔名的匯入項目新增至依附元件區段由於 ExoPlayer IMA 擴充功能的大小，您可以導入並啟用 Multidex.如果 minSdkVersion 設為 20 以下，就必須強制執行這項操作。此外，新增 compileOptions 以指定 Java 版本相容性資訊。

app/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 請求廣告所需的使用者權限。

app/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. 建立廣告 UI 容器

建立 StyledPlayerView，建立要做為 ExoPlayer PlayerView 的檢視畫面並提交適當 ID 的物件一併變更將 androidx.constraintlayout.widget.ConstraintLayout 轉換為 LinearLayout。

app/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. 為廣告請求新增內容網址和廣告代碼網址

將項目新增至 strings.xml，以儲存內容網址和 VAST 廣告代碼網址。

app/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. 匯入 ExoPlayer IMA 擴充功能

新增 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 物件 (包含廣告代碼網址)

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

，瞭解如何調查及移除這項存取權。

注意： 範例程式碼使用 Android SDK 適用的 onStart/onStop 24 以上版本，onResume/onPause 適用於 24 以下版本。

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

開始使用 Exoplayer IMA 擴充功能

IMA 用戶端總覽

必要條件

1. 建立新的 Android Studio 專案

2. 在專案中新增 ExoPlayer IMA 擴充功能

新增意圖宣告

3. 建立廣告 UI 容器

4. 為廣告請求新增內容網址和廣告代碼網址

5. 匯入 ExoPlayer IMA 擴充功能

6. 建立 adsLoader 執行個體

7. 初始化並釋出播放器

8. 處理播放器事件

6. 建立 `adsLoader` 執行個體