開始使用 Exoplayer IMA 擴充功能

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

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

IMA 用戶端總覽

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

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

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

必要條件

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

1. 建立新的 Android Studio 專案

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

1. 啟動 Android Studio。
2. 選取「Start a new Android Studio project」(啟動新的 Android Studio 專案)。
3. 在「Choose your project」(選擇專案) 頁面中，選取「Empty Activity」(空白活動) 範本。
4. 點選「下一步」。
5. 在「Configure your project」頁面中為專案命名，然後選取「Java」做為語言。
6. 按一下 [完成]。

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

，瞭解如何調查及移除這項存取權。 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 上的範例。