Penyisipan iklan

ExoPlayer dapat digunakan untuk penyisipan iklan sisi klien dan sisi server.

Penyisipan iklan sisi klien

Dalam penyisipan iklan sisi klien, pemutar beralih antara memuat media dari URL yang berbeda saat bertransisi antara konten yang diputar dan iklan. Informasi tentang iklan dimuat secara terpisah dari media, seperti dari tag iklan XML VAST atau VMAP. Hal ini dapat mencakup posisi isyarat iklan relatif terhadap awal konten, URI media iklan yang sebenarnya, dan metadata seperti apakah iklan tertentu dapat dilewati.

Saat menggunakan AdsMediaSource ExoPlayer untuk penyisipan iklan sisi klien, pemutar memiliki informasi tentang iklan yang akan diputar. Hal ini memiliki beberapa manfaat:

• Pemain dapat mengekspos metadata dan fungsi yang terkait dengan iklan yang menggunakan API-nya.
• Komponen UI ExoPlayer dapat menampilkan penanda untuk posisi iklan secara otomatis, dan mengubah perilakunya bergantung pada apakah iklan sedang diputar.
• Secara internal, pemutar dapat mempertahankan buffering yang konsisten di seluruh transisi antara iklan dan konten.

Dalam penyiapan ini, pemain menangani peralihan antara iklan dan konten, sehingga aplikasi tidak perlu berhati-hati dalam mengontrol beberapa pemutar latar/latar depan yang terpisah untuk iklan dan konten.

Saat menyiapkan video konten dan tag iklan untuk digunakan dengan penyisipan iklan sisi klien, idealnya iklan harus diposisikan pada sampel sinkronisasi (keyframe) di video konten sehingga pemutar dapat melanjutkan pemutaran konten dengan lancar.

Dukungan iklan deklaratif

URI tag iklan dapat ditentukan saat membuat MediaItem:

Kotlin

val mediaItem =
  MediaItem.Builder()
    .setUri(videoUri)
    .setAdsConfiguration(MediaItem.AdsConfiguration.Builder(adTagUri).build())
    .build()

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setAdsConfiguration(
            new MediaItem.AdsConfiguration.Builder(adTagUri).build())
        .build();

Untuk mengaktifkan dukungan pemutar untuk item media yang menentukan tag iklan, Anda harus mem-build dan memasukkan DefaultMediaSourceFactory yang dikonfigurasi dengan AdsLoader.Provider dan AdViewProvider saat membuat pemutar:

Kotlin

val mediaSourceFactory: MediaSource.Factory =
  DefaultMediaSourceFactory(context).setLocalAdInsertionComponents(adsLoaderProvider, playerView)
val player = ExoPlayer.Builder(context).setMediaSourceFactory(mediaSourceFactory).build()

Java

MediaSource.Factory mediaSourceFactory =
    new DefaultMediaSourceFactory(context)
        .setLocalAdInsertionComponents(adsLoaderProvider, /* adViewProvider= */ playerView);
ExoPlayer player =
    new ExoPlayer.Builder(context).setMediaSourceFactory(mediaSourceFactory).build();

Secara internal, DefaultMediaSourceFactory akan menggabungkan sumber media konten dalam AdsMediaSource. AdsMediaSource akan mendapatkan AdsLoader dari AdsLoader.Provider dan menggunakannya untuk menyisipkan iklan seperti yang ditentukan oleh tag iklan item media.

PlayerView ExoPlayer mengimplementasikan AdViewProvider. Library IMA ExoPlayer menyediakan AdsLoader yang mudah digunakan, seperti yang dijelaskan di bawah.

Playlist dengan iklan

Saat memutar playlist dengan beberapa item media, perilaku default-nya adalah meminta tag iklan dan menyimpan status pemutaran iklan satu kali untuk setiap kombinasi ID media, URI konten, dan URI tag iklan. Artinya, pengguna akan melihat iklan untuk setiap item media dengan iklan yang memiliki ID media atau URI konten yang berbeda, meskipun URI tag iklan cocok. Jika item media diulang, pengguna hanya akan melihat iklan yang sesuai satu kali (status pemutaran iklan menyimpan apakah iklan telah diputar, sehingga iklan akan dilewati setelah kemunculan pertamanya).

Anda dapat menyesuaikan perilaku ini dengan meneruskan ID iklan buram yang ditautkan dengan status pemutaran iklan untuk item media tertentu, berdasarkan kesetaraan objek. Berikut adalah contoh saat status pemutaran iklan ditautkan ke URI tag iklan saja, bukan kombinasi ID media dan URI tag iklan, dengan meneruskan URI tag iklan sebagai ID iklan. Efeknya adalah iklan hanya akan dimuat satu kali dan pengguna tidak akan melihat iklan di item kedua saat memutar playlist dari awal hingga akhir.

Kotlin

// Build the media items, passing the same ads identifier for both items,
// which means they share ad playback state so ads play only once.
val firstItem =
  MediaItem.Builder()
    .setUri(firstVideoUri)
    .setAdsConfiguration(MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build())
    .build()
val secondItem =
  MediaItem.Builder()
    .setUri(secondVideoUri)
    .setAdsConfiguration(MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build())
    .build()
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)

Java

// Build the media items, passing the same ads identifier for both items,
// which means they share ad playback state so ads play only once.
MediaItem firstItem =
    new MediaItem.Builder()
        .setUri(firstVideoUri)
        .setAdsConfiguration(
            new MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build())
        .build();
MediaItem secondItem =
    new MediaItem.Builder()
        .setUri(secondVideoUri)
        .setAdsConfiguration(
            new MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build())
        .build();
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);

Library IMA ExoPlayer

Library IMA ExoPlayer menyediakan ImaAdsLoader, sehingga memudahkan integrasi penyisipan iklan sisi klien ke dalam aplikasi Anda. Library ini menggabungkan fungsi IMA SDK sisi klien untuk mendukung penyisipan iklan VAST/VMAP. Untuk mengetahui petunjuk cara menggunakan library, termasuk cara menangani latar belakang dan melanjutkan pemutaran, lihat README.

Aplikasi demo menggunakan library IMA, dan menyertakan beberapa contoh tag iklan VAST/VMAP dalam daftar contoh.

Pertimbangan UI

PlayerView menyembunyikan kontrol transpornya selama pemutaran iklan secara default, tetapi aplikasi dapat mengalihkan perilaku ini dengan memanggil setControllerHideDuringAds. IMA SDK akan menampilkan tampilan tambahan di atas pemutar saat iklan diputar (misalnya, link "info selengkapnya" dan tombol lewati, jika berlaku).

Catatan: Karena pengiklan mengharapkan pengalaman yang konsisten di seluruh aplikasi, IMA SDK tidak memungkinkan penyesuaian tampilan yang ditampilkan saat iklan diputar. Oleh karena itu, tombol lewati tidak dapat dihapus atau diposisikan ulang, font tidak dapat diubah, atau penyesuaian lain tidak dapat dilakukan pada tampilan visual ini.

IMA SDK dapat melaporkan apakah iklan terhalang oleh tampilan yang disediakan aplikasi yang dirender di atas pemutar. Aplikasi yang perlu menempatkan tampilan yang penting untuk mengontrol pemutaran harus mendaftarkannya dengan IMA SDK sehingga tampilan tersebut dapat dihilangkan dari penghitungan visibilitas. Saat menggunakan PlayerView sebagai AdViewProvider, PlayerView akan otomatis mendaftarkan overlay kontrolnya. Aplikasi yang menggunakan UI pemutar kustom harus mendaftarkan tampilan overlay dengan menampilkannya dari AdViewProvider.getAdOverlayInfos.

Untuk mengetahui informasi selengkapnya tentang tampilan overlay, lihat Pengukuran Terbuka di IMA SDK.

Iklan pengiring

Beberapa tag iklan berisi iklan pengiring tambahan yang dapat ditampilkan di 'slot' di UI aplikasi. Slot ini dapat diteruskan melalui ImaAdsLoader.Builder.setCompanionAdSlots(slots). Untuk informasi selengkapnya, lihat Menambahkan Iklan Pengiring.

Iklan mandiri

IMA SDK dirancang untuk menyisipkan iklan ke dalam konten media, bukan untuk memutar iklan mandiri. Oleh karena itu, pemutaran iklan mandiri tidak didukung oleh library IMA. Sebaiknya gunakan Google Mobile Ads SDK untuk kasus penggunaan ini.

Menggunakan SDK iklan pihak ketiga

Jika Anda perlu memuat iklan melalui SDK iklan pihak ketiga, sebaiknya periksa apakah SDK tersebut sudah menyediakan integrasi ExoPlayer. Jika tidak, menerapkan AdsLoader kustom yang menggabungkan SDK iklan pihak ketiga adalah pendekatan yang direkomendasikan, karena memberikan manfaat AdsMediaSource yang dijelaskan di atas. ImaAdsLoader bertindak sebagai contoh implementasi.

Atau, Anda dapat menggunakan dukungan playlist ExoPlayer untuk membuat urutan iklan dan klip konten:

Kotlin

// A pre-roll ad.
val preRollAd = MediaItem.fromUri(preRollAdUri)
// The start of the content.
val contentStart =
  MediaItem.Builder()
    .setUri(contentUri)
    .setClippingConfiguration(ClippingConfiguration.Builder().setEndPositionMs(120000).build())
    .build()
// A mid-roll ad.
val midRollAd = MediaItem.fromUri(midRollAdUri)
// The rest of the content
val contentEnd =
  MediaItem.Builder()
    .setUri(contentUri)
    .setClippingConfiguration(ClippingConfiguration.Builder().setStartPositionMs(120000).build())
    .build()

// Build the playlist.
player.addMediaItem(preRollAd)
player.addMediaItem(contentStart)
player.addMediaItem(midRollAd)
player.addMediaItem(contentEnd)

Java

// A pre-roll ad.
MediaItem preRollAd = MediaItem.fromUri(preRollAdUri);
// The start of the content.
MediaItem contentStart =
    new MediaItem.Builder()
        .setUri(contentUri)
        .setClippingConfiguration(
            new ClippingConfiguration.Builder().setEndPositionMs(120_000).build())
        .build();
// A mid-roll ad.
MediaItem midRollAd = MediaItem.fromUri(midRollAdUri);
// The rest of the content
MediaItem contentEnd =
    new MediaItem.Builder()
        .setUri(contentUri)
        .setClippingConfiguration(
            new ClippingConfiguration.Builder().setStartPositionMs(120_000).build())
        .build();

// Build the playlist.
player.addMediaItem(preRollAd);
player.addMediaItem(contentStart);
player.addMediaItem(midRollAd);
player.addMediaItem(contentEnd);

Penyisipan iklan sisi server

Dalam penyisipan iklan sisi server (juga disebut penyisipan iklan dinamis, atau DAI), streaming media berisi iklan dan konten. Manifes DASH dapat mengarah ke segmen konten dan iklan, mungkin dalam periode terpisah. Untuk HLS, lihat dokumentasi Apple tentang memasukkan iklan ke dalam playlist.

Saat menggunakan penyisipan iklan sisi server, klien mungkin perlu me-resolve URL media secara dinamis untuk mendapatkan streaming yang digabungkan, klien mungkin perlu menampilkan overlay iklan di UI atau mungkin perlu melaporkan peristiwa ke SDK iklan atau server iklan.

DefaultMediaSourceFactory ExoPlayer dapat mendelegasikan semua tugas ini ke MediaSource penyisipan iklan sisi server untuk URI yang menggunakan skema ssai://:

Kotlin

val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setServerSideAdInsertionMediaSourceFactory(ssaiFactory)
    )
    .build()

Java

Player player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context)
                .setServerSideAdInsertionMediaSourceFactory(ssaiFactory))
        .build();

Library IMA ExoPlayer

Library IMA ExoPlayer menyediakan ImaServerSideAdInsertionMediaSource, sehingga mudah diintegrasikan dengan streaming iklan yang disisipkan sisi server IMA di aplikasi Anda. Library ini menggabungkan fungsi IMA DAI SDK untuk Android dan sepenuhnya mengintegrasikan metadata iklan yang diberikan ke dalam pemutar. Misalnya, hal ini memungkinkan Anda menggunakan metode seperti Player.isPlayingAd(), memproses transisi iklan konten dan memungkinkan pemutar menangani logika pemutaran iklan seperti melewati iklan yang sudah diputar.

Untuk menggunakan class ini, Anda perlu menyiapkan ImaServerSideAdInsertionMediaSource.AdsLoader dan ImaServerSideAdInsertionMediaSource.Factory, lalu menghubungkannya ke pemutar:

Kotlin

// MediaSource.Factory to load the actual media stream.
val defaultMediaSourceFactory = DefaultMediaSourceFactory(context)
// AdsLoader that can be reused for multiple playbacks.
val adsLoader =
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(context, adViewProvider).build()
// MediaSource.Factory to create the ad sources for the current player.
val adsMediaSourceFactory =
  ImaServerSideAdInsertionMediaSource.Factory(adsLoader, defaultMediaSourceFactory)
// Configure DefaultMediaSourceFactory to create both IMA DAI sources and
// regular media sources. If you just play IMA DAI streams, you can also use
// adsMediaSourceFactory directly.
defaultMediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory)
// Set the MediaSource.Factory on the Player.
val player = ExoPlayer.Builder(context).setMediaSourceFactory(defaultMediaSourceFactory).build()
// Set the player on the AdsLoader
adsLoader.setPlayer(player)

Java

// MediaSource.Factory to load the actual media stream.
DefaultMediaSourceFactory defaultMediaSourceFactory = new DefaultMediaSourceFactory(context);
// AdsLoader that can be reused for multiple playbacks.
ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader =
    new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(context, adViewProvider).build();
// MediaSource.Factory to create the ad sources for the current player.
ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
    new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, defaultMediaSourceFactory);
// Configure DefaultMediaSourceFactory to create both IMA DAI sources and
// regular media sources. If you just play IMA DAI streams, you can also use
// adsMediaSourceFactory directly.
defaultMediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);
// Set the MediaSource.Factory on the Player.
Player player =
    new ExoPlayer.Builder(context).setMediaSourceFactory(defaultMediaSourceFactory).build();
// Set the player on the AdsLoader
adsLoader.setPlayer(player);

Muat kunci aset IMA, atau ID sumber konten dan ID video, dengan membuat URL dengan ImaServerSideAdInsertionUriBuilder:

Kotlin

val ssaiUri =
  ImaServerSideAdInsertionUriBuilder()
    .setAssetKey(assetKey)
    .setFormat(C.CONTENT_TYPE_HLS)
    .build()
player.setMediaItem(MediaItem.fromUri(ssaiUri))

Java

Uri ssaiUri =
    new ImaServerSideAdInsertionUriBuilder()
        .setAssetKey(assetKey)
        .setFormat(C.CONTENT_TYPE_HLS)
        .build();
player.setMediaItem(MediaItem.fromUri(ssaiUri));

Terakhir, lepaskan loader iklan setelah tidak digunakan lagi:

Kotlin

adsLoader.release()

Java

adsLoader.release();

Catatan: Saat ini, hanya satu aliran penyisipan iklan sisi server IMA yang didukung dalam playlist yang sama. Anda dapat menggabungkan streaming dengan media lain, tetapi tidak dengan streaming penyisipan iklan sisi server IMA lainnya.

Pertimbangan UI

Pertimbangan UI yang sama seperti penyisipan iklan sisi klien juga berlaku untuk penyisipan iklan sisi server.

Iklan pengiring

Beberapa tag iklan berisi iklan pengiring tambahan yang dapat ditampilkan di 'slot' pada UI aplikasi. Slot ini dapat diteruskan melalui ImaServerSideAdInsertionMediaSource.AdsLoader.Builder.setCompanionAdSlots(slots). Untuk informasi selengkapnya, lihat Menambahkan Iklan Pengiring.

Menggunakan SDK iklan pihak ketiga

Jika Anda perlu memuat iklan menggunakan SDK iklan pihak ketiga, sebaiknya periksa apakah SDK tersebut sudah menyediakan integrasi ExoPlayer. Jika tidak, sebaiknya berikan MediaSource kustom yang menerima URI dengan skema ssai:// yang mirip dengan ImaServerSideAdInsertionMediaSource.

Logika sebenarnya untuk membuat struktur iklan dapat didelegasikan ke ServerSideAdInsertionMediaSource umum, yang menggabungkan MediaSource streaming dan memungkinkan pengguna menetapkan serta memperbarui AdPlaybackState yang mewakili metadata iklan.

Sering kali, streaming iklan yang disisipkan sisi server berisi peristiwa berwaktu untuk memberi tahu pemutar tentang metadata iklan. Lihat format yang didukung untuk mengetahui informasi tentang format metadata berwaktu yang didukung oleh ExoPlayer. Penerapan MediaSource SDK iklan kustom dapat memproses peristiwa metadata berjangka waktu dari pemutar menggunakan Player.Listener.onMetadata.