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 dibutuhkan untuk mengintegrasikan IMA dengan fitur.
Mengurangi waktu pengembangan yang dibutuhkan untuk mengupdate ke versi baru IMA.

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 sebagai contoh dengan aplikasi contoh yang 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 IMA ExoPlayer ke project Anda

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

Mengonfigurasi aplikasi Anda untuk dan mengaktifkan multidex. Hal ini diperlukan karena ke ukuran ekstensi, dan diperlukan untuk aplikasi dengan minSdkVersion yang disetel ke Android 4.4W (level API 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 yang 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

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 contoh aliran data IMA halaman untuk melihat contoh streaming aset untuk menguji proyek. Lihat juga bagian Ad Manager tentang DAI untuk informasi cara menyiapkan streaming Anda sendiri.

Langkah ini menunjukkan penyiapan live stream, tetapi IMA ExoPlayer ekstensi juga mendukung streaming VOD DAI. Lihat langkah untuk video on-demand (VOD) feed 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 ini feed Anda. Lebih banyak streaming tersedia untuk diuji Contoh halaman streaming IMA.

Buat konstanta KEY_ADS_LOADER_STATE untuk menyimpan dan mengambil AdsLoader state.

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 metode yang disimpan AdsLoader.State, 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 menginisialisasi pemain

Tambahkan metode untuk menginisialisasi pemutar dan melakukan 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);
  }
}

Tambahkan metode untuk melepaskan pemutar

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 aliran data pemutaran.

Untuk mendukung Android SDK versi 24+:

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

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

Langkah ini juga menggunakan onSaveInstanceState() peristiwa 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 diminta untuk memutar konten VOD dengan iklan, Anda harus melakukannya 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. Anda sekarang meminta dan memutar streaming media dengan ExoPlayer ekstensi IMA. Lihat contoh DAI Android di GitHub untuk kode lengkapnya.

Memulai ekstensi IMA ExoPlayer

Prasyarat

Membuat project Android Studio baru

Menambahkan ekstensi IMA ExoPlayer 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 menginisialisasi pemain

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

Tambahkan metode untuk melepaskan pemutar

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