Memulai ekstensi IMA ExoPlayer

ExoPlayer adalah pemutar media Android. Panduan ini menunjukkan cara menggunakan ekstensi IMA ExoPlayer. Ekstensi ini menggunakan IMA DAI SDK untuk meminta dan memutar streaming media dengan iklan dan konten.

Berikut adalah manfaat ekstensi:

• Menyederhanakan kode yang diperlukan untuk mengintegrasikan fitur IMA.
• Mengurangi waktu yang diperlukan untuk mengupdate ke versi IMA baru.

Ekstensi IMA ExoPlayer mendukung protokol streaming HLS dan DASH. Berikut ringkasannya:

Dukungan streaming ekstensi ExoPlayer-IMA
	Livestream	Streaming VOD
HLS
DASH

ExoPlayer-IMA versi 1.1.0 dan yang lebih baru mendukung live stream DASH.

Panduan ini menggunakan panduan ExoPlayer untuk membantu Anda membuat aplikasi lengkap dan mengintegrasikan ekstensi. Untuk aplikasi contoh lengkap, lihat ExoPlayerExample di GitHub.

Prasyarat

• Android Studio
• AndroidX Media3 ExoPlayer versi 1.0.0 atau yang lebih baru untuk dukungan DAI.

Buat project Android Studio baru

Untuk membuat project Android Studio, ikuti langkah-langkah berikut:

1. Mulai Android Studio.
2. Pilih Start a new Android Studio project.
3. Di halaman Choose your project, pilih template No Activity.
4. Klik Berikutnya.
5. Di halaman Configure your project, beri nama project Anda dan pilih Java sebagai bahasa. Catatan: IMA DAI SDK berfungsi dengan Kotlin, tetapi panduan ini menggunakan contoh Java.

• Klik Selesai.

Menambahkan ekstensi IMA ExoPlayer ke project Anda

Untuk menambahkan ekstensi IMA ExoPlayer, lakukan hal berikut:

1. Sertakan impor berikut di bagian dependencies pada file build.gradle aplikasi Anda:

   dependencies {
       def media3_version = "1.8.0"
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
       implementation 'androidx.appcompat:appcompat:1.7.1'
       implementation "androidx.media3:media3-ui:$media3_version"
       implementation "androidx.media3:media3-exoplayer:$media3_version"
       implementation "androidx.media3:media3-exoplayer-hls:$media3_version"
       implementation "androidx.media3:media3-exoplayer-dash:$media3_version"
   
       // The library adds the IMA ExoPlayer integration for ads.
       implementation "androidx.media3:media3-exoplayer-ima:$media3_version"
   }
   build.gradle
   

2. Tambahkan izin pengguna yang diperlukan IMA DAI SDK untuk meminta iklan:

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   AndroidManifest.xml
   

Menyiapkan UI ExoPlayer

Untuk menyiapkan UI ExoPlayer, lakukan hal berikut:

1. Buat objek PlayerView untuk ExoPlayer.

2. Ubah tampilan androidx.constraintlayout.widget.ConstraintLayout menjadi tampilan LinearLayout, seperti yang direkomendasikan oleh ekstensi IMA ExoPlayer:

   <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:fitsSystemWindows="true"
           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
   

Tambahkan parameter streaming

Lihat halaman contoh streaming IMA untuk aset streaming contoh guna menguji project Anda. Untuk menyiapkan streaming Anda sendiri, lihat bagian Ad Manager di DAI.

Langkah ini menyiapkan livestream. Ekstensi IMA ExoPlayer juga mendukung streaming VOD DAI. Untuk mempelajari perubahan yang diperlukan aplikasi Anda untuk streaming VOD, lihat langkah-langkah untuk streaming video on demand (VOD).

Mengimpor ekstensi IMA ExoPlayer

1. Tambahkan pernyataan impor berikut untuk ekstensi ExoPlayer:

   import static androidx.media3.common.C.CONTENT_TYPE_HLS;
   
   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.common.util.Util;
   import androidx.media3.datasource.DataSource;
   import androidx.media3.datasource.DefaultDataSource;
   import androidx.media3.exoplayer.ExoPlayer;
   import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionMediaSource;
   import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder;
   import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
   import androidx.media3.ui.PlayerView;
   import com.google.ads.interactivemedia.v3.api.AdEvent;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
   import java.util.HashMap;
   import java.util.Map;
   MyActivity.java
   

2. Di MyActivity.java, tambahkan variabel pribadi ini:

   • PlayerView
   • ExoPlayer
   • ImaServerSideAdInsertionMediaSource.AdsLoader
   • ImaServerSideAdInsertionMediaSource.AdsLoader.State

   Untuk menguji dengan streaming HLS Big Buck Bunny (Live), tambahkan kunci asetnya. Anda dapat menemukan lebih banyak streaming untuk diuji di halaman streaming contoh IMA.

3. Buat konstanta KEY_ADS_LOADER_STATE untuk menyimpan dan mengambil status AdsLoader:

   /** Main Activity. */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   public class MyActivity extends Activity {
   
     private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
     private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
     private static final String LOG_TAG = "ImaExoPlayerExample";
   
     private PlayerView playerView;
     private TextView logText;
     private ExoPlayer player;
     private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
     private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;
     private ImaSdkSettings imaSdkSettings;
   MyActivity.java
   

Buat instance adsLoader

Ganti metode onCreate. Di dalamnya, temukan PlayerView dan periksa apakah ada AdsLoader.State yang disimpan. Anda dapat menggunakan status ini saat menginisialisasi objek adsLoader.

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

  // 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);

  // Checks if there is a saved AdsLoader state to be used later when initiating the AdsLoader.
  if (savedInstanceState != null) {
    Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE);
    if (adsLoaderStateBundle != null) {
      adsLoaderState =
          ImaServerSideAdInsertionMediaSource.AdsLoader.State.fromBundle(adsLoaderStateBundle);
    }
  }
}

private ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    // Set any IMA SDK settings here.
  }
  return imaSdkSettings;
}
MyActivity.java

Menambahkan metode untuk menginisialisasi pemutar

Tambahkan metode untuk menginisialisasi pemutar. Metode ini harus melakukan hal berikut:

• Buat instance AdsLoader.
• Buat ExoPlayer.
• Buat MediaItem menggunakan kunci aset live stream.
• Tetapkan MediaItem untuk pemain Anda.

// Create a server side ad insertion (SSAI) AdsLoader.
private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
      new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

  // Attempts to set the AdsLoader state if available from a previous session.
  if (adsLoaderState != null) {
    adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
  }

  return adsLoaderBuilder
      .setAdEventListener(buildAdEventListener())
      .setImaSdkSettings(getImaSdkSettings())
      .build();
}

private void initializePlayer() {
  adsLoader = createAdsLoader();

  // Set up the factory for media sources, passing the ads loader.
  DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

  DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory);

  // MediaSource.Factory to create the ad sources for the current player.
  ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
      new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory);

  // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory.
  // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server
  // side inserted ad streams.
  mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);

  // Create a SimpleExoPlayer 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 stream URI.
  Uri ssaiUri = buildLiveStreamUri(SAMPLE_ASSET_KEY, CONTENT_TYPE_HLS);
  MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiUri);

  // Prepare the content and ad to be played with the ExoPlayer.
  player.setMediaItem(ssaiMediaItem);
  player.prepare();

  // Set PlayWhenReady. If true, content and ads will autoplay.
  player.setPlayWhenReady(false);
}

/**
 * Builds an IMA SSAI live stream URI for the given asset key and format.
 *
 * @param assetKey The asset key of the live stream.
 * @param format The format of the live stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the live stream.
 */
public Uri buildLiveStreamUri(String assetKey, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setAssetKey(assetKey)
      .setFormat(format)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

Menambahkan metode untuk melepaskan pemain

Tambahkan metode untuk melepaskan pemain. Metode ini harus melakukan tindakan berikut secara berurutan:

• Tetapkan referensi pemutar ke null dan lepaskan resource pemutar.
• Lepaskan status adsLoader.

private void releasePlayer() {
  // Set the player references to null and release the player's resources.
  playerView.setPlayer(null);
  player.release();
  player = null;

  // Release the adsLoader state so that it can be initiated again.
  adsLoaderState = adsLoader.release();
}
MyActivity.java

Menangani peristiwa pemutar

Untuk menangani peristiwa pemutar, buat callback untuk peristiwa siklus proses aktivitas guna mengelola pemutaran streaming.

Untuk level API Android 24 dan yang lebih baru, gunakan metode berikut:

• onStart()
• onStop()

Untuk level API Android yang lebih lama dari 24, gunakan metode berikut:

• onResume()
• onPause()

Metode onStart() dan onResume() dipetakan ke playerView.onResume(), sedangkan onStop() dan onPause() dipetakan ke playerView.onPause().

Langkah ini juga menggunakan peristiwa onSaveInstanceState() untuk menyimpan adsLoaderState.

@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
public void onSaveInstanceState(Bundle outState) {
  // Attempts to save the AdsLoader state to handle app backgrounding.
  if (adsLoaderState != null) {
    outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle());
  }
}
MyActivity.java

Penyiapan streaming VOD (opsional)

Jika aplikasi Anda perlu memutar konten VOD dengan iklan, ikuti langkah-langkah berikut:

1. Tambahkan CMS ID dan Video ID untuk streaming VOD. Untuk pengujian, gunakan parameter streaming berikut:
   • ID CMS: "2548831"
   • ID Video: "tears-of-steel"

2. Buat URI VOD SSAI menggunakan metode ImaServerSideAdInsertionUriBuilder():

   /**
    * Builds an IMA SSAI VOD stream URI for the given CMS ID, video ID, and format.
    *
    * @param cmsId The CMS ID of the VOD stream.
    * @param videoId The video ID of the VOD stream.
    * @param format The format of the VOD stream request, either {@code CONTENT_TYPE_HLS} or {@code
    *     CONTENT_TYPE_DASH}.
    * @return The URI of the VOD stream.
    */
   public Uri buildVodStreamUri(String cmsId, String videoId, int format) {
     Map<String, String> adTagParams = new HashMap<String, String>();
     // Update the adTagParams map with any parameters.
     // For more information, see https://support.google.com/admanager/answer/7320899
   
     return new ImaServerSideAdInsertionUriBuilder()
         .setContentSourceId(cmsId)
         .setVideoId(videoId)
         .setFormat(format)
         .setAdTagParameters(adTagParams)
         .build();
   }
   MyActivity.java
   

3. Tetapkan URI streaming VOD baru sebagai item media pemutar Anda menggunakan metode MediaItem.fromUri().

Jika berhasil, Anda dapat meminta dan memutar streaming media dengan ekstensi IMA ExoPlayer. Untuk contoh lengkapnya, lihat Contoh DAI Android di GitHub.