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 dengan iklan dan konten.
Berikut 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 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 mengetahui contoh dengan
aplikasi contoh lengkap.
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.
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 tinggi, versi IMA DAI SDK saat ini dan terbaru memerlukan deklarasi intent eksplisit untuk membuka link web. 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
Tambahkan 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. Lebih banyak streaming 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
Ganti metode onCreate
untuk menemukan PlayerView
dan periksa
AdsLoader.State
yang disimpan,
yang dapat digunakan saat memulai objek adsLoader
.
Selain itu, aktifkan multidex jika diperlukan oleh jumlah metode dan minSdkVersion
aplikasi Anda
(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. - Tetapkan
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 merilis pemain dalam urutan ini:
- Tetapkan referensi pemutar ke null dan lepaskan resource pemutar.
- Lepaskan 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()
, serta 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
danVideo 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 kini meminta dan memutar streaming media dengan ekstensi IMA ExoPlayer. Lihat contoh DAI Android di GitHub untuk mengetahui kode lengkapnya.