Memulai ekstensi IMA ExoPlayer

ExoPlayer adalah pemutar media tingkat aplikasi untuk Android. Panduan ini menunjukkan cara menggunakan ekstensi IMA ExoPlayer, yang menggabungkan IMA Android DAI SDK, untuk meminta dan memutar streaming media dengan iklan dan konten.

Berikut ini beberapa manfaat ekstensi:

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

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

Dukungan streaming ekstensi ExoPlayer-IMA
	Livestream	Streaming VOD
HLS
DASH

Live stream DASH didukung di ExoPlayer-IMA versi 1.1.0+.

Panduan ini didasarkan pada panduan ExoPlayer, dan menunjukkan cara membuat aplikasi lengkap dan mengintegrasikan ekstensi. Lihat ExoPlayerExample dari GitHub untuk contoh dengan aplikasi contoh lengkap.

Poin Penting: Ekstensi IMA ExoPlayer bergantung pada ExoPlayer. Jika Anda lebih suka menggunakan pemutar lain, ikuti Panduan memulai untuk mengintegrasikan IMA DAI SDK ke aplikasi Anda.

Prasyarat

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

Membuat project Android Studio baru

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

• Mulai Android Studio.
• Pilih Start a new Android Studio project.
• Di halaman Choose your project, pilih template No Activity.
• Klik Berikutnya.

• Di halaman Configure your project, beri nama project Anda dan pilih Java untuk bahasa.

  Catatan: IMA DAI SDK kompatibel dengan Kotlin. Namun, contoh yang dibahas dalam panduan ini menggunakan Java.

• Klik Selesai.

Menambahkan ekstensi IMA ExoPlayer ke project Anda

Tambahkan impor untuk ekstensi ke file build.gradle tingkat aplikasi di bagian dependencies.

Konfigurasikan aplikasi Anda untuk dan aktifkan multidex. Hal ini diperlukan karena ukuran ekstensi, dan diperlukan untuk aplikasi dengan minSdkVersion yang ditetapkan ke Android 4.4W (API level 20) atau yang lebih rendah.

Berikut contohnya:

app/build.gradle

android {

  ...

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

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.1.1'
    implementation 'androidx.media3:media3-exoplayer:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-hls:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-dash:1.1.1'

    // Adding the ExoPlayer IMA extension for ads will also include the IMA
    // SDK as a dependency.
    implementation 'androidx.media3:media3-exoplayer-ima:1.1.1'
}

Tambahkan izin pengguna yang diperlukan oleh IMA SDK untuk meminta iklan:

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>

Menambahkan deklarasi intent

Jika aplikasi Anda menargetkan Android 11 (level API 30) atau yang lebih baru, versi IMA SDK saat ini dan terbaru memerlukan deklarasi intent eksplisit untuk membuka link web. Tambahkan cuplikan berikut ke file manifes aplikasi untuk mengaktifkan klik-tayang iklan (pengguna mengklik tombol Pelajari lebih lanjut).

Catatan: Versi IMA SDK mendatang akan otomatis menyertakan deklarasi ini dan akan digabungkan dengan file manifes aplikasi Anda.

  <?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>

Menyiapkan UI ExoPlayer

Membuat objek PlayerView yang akan digunakan oleh ExoPlayer.

Ubah androidx.constraintlayout.widget.ConstraintLayout menjadi LinearLayout, yang direkomendasikan untuk ekstensi IMA ExoPlayer.

Berikut contohnya:

app/src/main/res/layout/activity_my.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:background="@android:color/black"
    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="match_parent" />

</LinearLayout>

Menambahkan parameter streaming

Lihat halaman contoh streaming IMA untuk melihat contoh aset aliran data guna menguji project Anda. Lihat juga bagian Ad Manager di DAI untuk mengetahui informasi tentang cara menyiapkan streaming Anda sendiri.

Langkah ini menunjukkan penyiapan live stream, tetapi ekstensi IMA ExoPlayer juga mendukung streaming VOD DAI. Lihat langkah untuk streaming video on-demand (VOD) untuk mengetahui perubahan yang diperlukan aplikasi Anda untuk menangani streaming VOD.

Mengimpor ekstensi IMA ExoPlayer

Menambahkan pernyataan impor untuk ekstensi ExoPlayer.

Tambahkan variabel pribadi berikut ke MyActivity.java:

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

Tambahkan kunci aset streaming HLS Big Buck Bunny (Live) untuk diuji dengan streaming ini. Streaming lainnya tersedia untuk diuji di halaman streaming contoh IMA.

Buat konstanta KEY_ADS_LOADER_STATE untuk menyimpan dan mengambil status AdsLoader.

Berikut contohnya:

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

import static androidx.media3.common.C.CONTENT_TYPE_HLS;

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.annotation.OptIn;
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.exoplayer.util.EventLogger;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

}

Membuat instance adsLoader

Timpa metode onCreate untuk menemukan PlayerView dan memeriksa AdsLoader.State tersimpan, yang dapat digunakan saat memulai objek adsLoader.

Selain itu, aktifkan multidex jika diperlukan oleh jumlah metode aplikasi dan minSdkVersion (seperti yang dijelaskan di langkah 2).

Berikut contohnya:

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

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

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

    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.CREATOR.fromBundle(
                adsLoaderStateBundle);
      }
    }
  }

}

Menambahkan metode untuk melakukan inisialisasi pada pemutar

Tambahkan metode untuk melakukan inisialisasi pada pemutar dan lakukan hal berikut:

• Buat instance AdsLoader.
• Buat ExoPlayer.
• Buat MediaItem dengan kunci aset live stream.
• Setel MediaItem ke pemutar Anda.

Catatan: Bagian ini menggunakan metode dengan nama yang merujuk pada konsep penyisipan iklan sisi server (SSAI).

• DAI Google Ad Manager adalah instance SSAI.
• Penerapan ekstensi IMA ExoPlayer panduan ini dirancang untuk berfungsi secara khusus dengan DAI Ad Manager. Ekstensi IMA ExoPlayer juga mendukung instance SSAI lainnya, seperti Google Cloud Platform, yang tidak ditunjukkan dalam panduan ini.

Berikut contohnya:

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

public class MyActivity extends Activity {

  ...

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

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

    return adsLoaderBuilder.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 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);

    // Build an IMA SSAI media item to prepare the player with.
    Uri ssaiLiveUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setAssetKey(SAMPLE_ASSET_KEY)
            .setFormat(CONTENT_TYPE_HLS) // Use CONTENT_TYPE_DASH for dash streams.
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiLiveUri);

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

Tambahkan metode untuk melepaskan pemutar

Tambahkan metode untuk melepaskan pemutar dalam urutan ini:

• Setel referensi pemutar ke null dan lepaskan resource pemain.
• Melepaskan status adsLoader.

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

public class MyActivity extends Activity {

  ...

  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();
  }

Menangani peristiwa pemain

Terakhir, buat callback untuk peristiwa siklus proses aktivitas guna menangani pemutaran streaming.

Untuk mendukung Android SDK versi 24 atau yang lebih baru:

• onStart()
• onStop()

Untuk mendukung Android SDK versi yang lebih lama dari 24: - onResume() - onPause()

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

Poin Penting: Contoh ini berupaya mendukung Android SDK versi 24+ dan versi yang lebih rendah dari 24. Gunakan onStart()/onStop() untuk dukungan Android SDK versi 24+, dan onResume()/onPause() untuk versi yang lebih rendah dari 24.

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

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

public class MyActivity extends Activity {

  ...

  @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());
    }
  }

  ...

}

Penyiapan streaming VOD (opsional)

Jika aplikasi Anda diwajibkan untuk memutar konten VOD dengan iklan, Anda harus melakukan hal berikut:

1. Tambahkan CMS ID dan Video ID untuk streaming uji coba VOD.
2. Buat URI VOD SSAI menggunakan ImaServerSideAdInsertionUriBuilder().
3. Gunakan URI baru ini sebagai item media pemutar Anda.

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

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 SAMPLE_CMS_ID = "2528370";
  private static final String SAMPLE_VIDEO_ID = "tears-of-steel";

  ...

  private void initializePlayer() {

     ...

    Uri ssaiVodUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setContentSourceId(SAMPLE_CMS_ID)
            .setVideoId(SAMPLE_VIDEO_ID)
            .setFormat(CONTENT_TYPE_HLS)
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiVodUri);

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

Selesai. Anda sekarang meminta dan memutar streaming media dengan ekstensi IMA ExoPlayer. Lihat contoh DAI Android di GitHub untuk kode lengkapnya.