Halaman ini diterjemahkan oleh Cloud Translation API.

Memulai ekstensi IMA ExoPlayer

ExoPlayer adalah pemutar media tingkat aplikasi untuk Android. Panduan ini menunjukkan cara menggunakan Ekstensi IMA ExoPlayer, yang menggabungkan IMA DAI SDK, untuk meminta dan memutar streaming media 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 IMA baru.

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

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 ExoPlayer , dan menunjukkan cara membuat aplikasi lengkap dan mengintegrasikan ekstensi. Lihat ExoPlayerExample dari GitHub untuk mengetahui contoh dengan aplikasi contoh lengkap.

Prasyarat

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

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 ExoPlayer IMA ke project Anda

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

Konfigurasikan aplikasi Anda untuk mengaktifkan 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 21
      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 DAI 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 DAI 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 (API level 30) atau yang lebih baru, versi saat ini dan yang terbaru versi IMA DAI SDK memerlukan pernyataan niat yang eksplisit untuk membuka penautan. Tambahkan cuplikan berikut ke file manifes aplikasi Anda untuk mengaktifkan klik-tayang iklan (pengguna mengklik tombol Pelajari lebih lanjut).

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

Buat 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 streaming contoh IMA untuk aset streaming contoh guna menguji project Anda. Lihat juga bagian Ad Manager di DAI untuk mendapatkan informasi tentang cara menyiapkan streaming Anda sendiri.

Langkah ini menunjukkan cara menyiapkan live stream, tetapi ekstensi IMA ExoPlayer juga mendukung streaming VOD DAI. Lihat langkah untuk streaming video on demand (VOD) untuk melihat 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:

Tambahkan kunci aset streaming HLS Big Buck Bunny (Live) untuk diuji dengan streaming ini. Lebih banyak streaming tersedia untuk diuji Contoh halaman streaming IMA.

Buat konstanta KEY_ADS_LOADER_STATE untuk menyimpan dan mengambil AdsLoader status.

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`

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

Selain itu, aktifkan multidex jika diperlukan oleh jumlah metode aplikasi Anda dan minSdkVersion (seperti yang dijelaskan dalam 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.fromBundle(
                adsLoaderStateBundle);
      }
    }
  }

}

Menambahkan metode untuk melakukan inisialisasi pemutar

Tambahkan metode untuk melakukan inisialisasi pemutar dan lakukan hal berikut:

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

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

Menambahkan metode untuk merilis pemain

Tambahkan metode untuk melepaskan pemutar dalam urutan ini:

Setel referensi pemain ke null dan melepaskan resource pemain.
Rilis 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+:

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

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

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:

Tambahkan CMS ID dan Video ID untuk streaming pengujian VOD.
Buat URI VOD SSAI menggunakan ImaServerSideAdInsertionUriBuilder().
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 = "2548831";
  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. Sekarang Anda meminta dan memutar streaming media dengan ekstensi IMA ExoPlayer. Lihat contoh DAI Android di GitHub untuk mengetahui kode lengkapnya.

Memulai ekstensi IMA ExoPlayer

Prasyarat

Membuat project Android Studio baru

Menambahkan ekstensi ExoPlayer IMA ke project Anda

app/build.gradle

app/src/main/AndroidManifest.xml

Menambahkan deklarasi intent

Menyiapkan UI ExoPlayer

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

Menambahkan parameter streaming

Mengimpor ekstensi IMA ExoPlayer

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

Membuat instance adsLoader

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

Menambahkan metode untuk melakukan inisialisasi pemutar

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

Menambahkan metode untuk merilis pemain

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

Menangani peristiwa pemain

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

Penyiapan streaming VOD (opsional)

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

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

Membuat instance `adsLoader`

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

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

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

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

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