ExoPlayer, Android için uygulama düzeyinde bir medya oynatıcıdır. Bu kılavuzda, hem reklamlar hem de içerikle bir medya akışı isteğinde bulunmak ve bunları oynatmak için IMA DAI SDK'sını sarmalayan ExoPlayer IMA uzantısını nasıl kullanabileceğiniz gösterilmektedir.
Uzantının avantajlarından bazıları şunlardır:
- IMA'yı özelliklerle entegre etmek için gereken kodu basitleştirir.
- IMA'nın yeni sürümlerine güncelleme yapmak için gereken geliştirme süresini kısaltır.
ExoPlayer IMA uzantısı, HLS ve DASH akış protokollerini destekler. Aşağıda bir özet verilmiştir:
ExoPlayer-IMA uzantı akış desteği | ||
---|---|---|
Canlı yayın | VOD akışları | |
HLS | ![]() |
![]() |
DASH | ![]() |
![]() |
DASH canlı yayınları, ExoPlayer-IMA'nın 1.1.0 ve sonraki sürümlerinde desteklenir.
Bu kılavuz, ExoPlayer kılavuzuna dayalı olup tam bir uygulamanın nasıl oluşturulacağı ve uzantının nasıl entegre edileceği gösterilmektedir. Eksiksiz bir örnek uygulamanın yer aldığı bir örnek için GitHub'daki ExoPlayerExample
bölümüne bakın.
Ön koşullar
- Android Studio
- DAI desteği için AndroidX Media3 ExoPlayer 1.0.0 sürümü veya üzeri.
Yeni Android Studio projesi oluştur
Android Studio projenizi oluşturmak için aşağıdaki adımları tamamlayın:
- Android Studio'yu başlatın.
- Yeni bir Android Studio projesi başlat'ı seçin.
- Projenizi seçin sayfasında Etkinlik Yok şablonunu seçin.
- İleri'yi tıklayın.
Projenizi yapılandırın sayfasında projenize bir ad verin ve dil olarak Java'yı seçin.
Son'u tıklayın.
ExoPlayer IMA uzantısını projenize ekleme
dependencies
bölümünde, uygulama düzeyindeki build.gradle dosyasına uzantı için içe aktarma işlemleri ekleyin.
Uygulamanızı multidex'i yapılandırın ve etkinleştirin. Bu işlem, uzantının boyutu nedeniyle gereklidir ve minSdkVersion
özelliği Android 4.4W (API düzeyi 20) veya önceki sürüme ayarlanmış uygulamalar için gereklidir.
Aşağıda bir örnek verilmiştir:
uygulama/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' }
Reklam isteğinde bulunmak için IMA DAI SDK'sı tarafından gereken kullanıcı izinlerini ekleyin:
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>
Amaç bildirimleri ekleyin
Uygulamanız Android 11 (API düzeyi 30) veya sonraki sürümleri hedefliyorsa IMA DAI SDK'sının mevcut ve son sürümleri, web bağlantılarını açmak için açık bir niyet beyanı gerektirir. Reklam tıklamalarını (kullanıcılar Daha fazla bilgi düğmesini tıklar) etkinleştirmek için uygulamanızın manifest dosyasına aşağıdaki snippet'i ekleyin.
<?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>
ExoPlayer'ın kullanıcı arayüzünü ayarlama
ExoPlayer tarafından kullanılacak PlayerView
nesnesini oluşturun.
androidx.constraintlayout.widget.ConstraintLayout
değerini bir LinearLayout
olarak değiştirin. Bu, ExoPlayer IMA uzantısı için önerilir.
Aşağıda bir örnek verilmiştir:
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>
Akış parametrelerinizi ekleyin
Projenizi test etmek üzere örnek akış öğeleri için IMA örnek akışı sayfasına göz atın. Kendi akışlarınızı ayarlama hakkında bilgi için DAI'daki Ad Manager bölümüne de bakın.
Bu adımda, canlı yayın oluşturma işlemi gösterilmektedir. Ancak ExoPlayer IMA uzantısı DAI VOD akışlarını da destekler. Uygulamanızın VOD akışlarını işlemek üzere hangi değişikliklere ihtiyacı olduğunu görmek için talebe bağlı video (VOD) akışlarına yönelik adıma bakın.
ExoPlayer IMA uzantısını içe aktarma
ExoPlayer uzantısı için içe aktarma ifadelerini ekleyin.
Aşağıdaki gizli değişkenleri MyActivity.java
öğesine ekleyin:
PlayerView
ExoPlayer
ImaServerSideAdInsertionMediaSource.AdsLoader
ImaServerSideAdInsertionMediaSource.AdsLoader.State
Bu akışla test etmek için Big Buck Bunny (Canlı) HLS akışının öğe anahtarını ekleyin. IMA'nın örnek akış sayfasında test edebileceğiniz daha fazla akış mevcuttur.
AdsLoader
durumunu kaydedip almak için KEY_ADS_LOADER_STATE
sabit değeri oluşturun.
Aşağıda bir örnek verilmiştir:
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; }
adsLoader
örneği oluşturun
PlayerView
öğesini bulmak ve adsLoader
nesnesini başlatırken kullanılabilecek kayıtlı bir AdsLoader.State
olup olmadığını kontrol etmek için onCreate
yönteminin üzerine yazın.
Ayrıca, uygulamanızın yöntem sayısı ve minSdkVersion
özelliği (2. adımda açıklandığı gibi) gerekiyorsa multidex'i etkinleştirin.
Aşağıda bir örnek verilmiştir:
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); } } } }
Oynatıcıyı başlatmak için yöntemler ekleyin
Oynatıcıyı başlatmak için bir yöntem ekleyin ve aşağıdakileri yapın:
AdsLoader
örneği oluşturun.ExoPlayer
oluşturun.- Canlı yayının öğe anahtarıyla bir
MediaItem
oluşturun. MediaItem
değerini oynatıcınıza ayarlayın.
Aşağıda bir örnek verilmiştir:
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); } }
Oynatıcıyı serbest bırakmak için bir yöntem ekleyin
Oynatıcıyı bu dizide serbest bırakmak için bir yöntem ekleyin:
- Oynatıcı referanslarını null değerine ayarlayın ve oynatıcının kaynaklarını serbest bırakın.
adsLoader
öğesinin durumunu bırakın.
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(); }
Oyuncu etkinliklerini işleme
Son olarak, akış oynatmayı yönetmek amacıyla etkinliğin yaşam döngüsü etkinlikleri için geri çağırmalar oluşturun.
Android SDK 24 ve sonraki sürümlerini desteklemek için:
Android SDK 24'ten önceki sürümleri desteklemek için:
- onResume()
- onPause()
onStart()
ve onResume()
, playerView.onResume()
ile eşlenirken onStop()
ve onPause()
, playerView.onPause()
ile eşlenir.
Bu adım, adsLoaderState
dosyasını kaydetmeyi denemek için onSaveInstanceState()
etkinliğini de kullanır.
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()); } } ... }
VOD akışı kurulumu (isteğe bağlı)
Uygulamanızın reklam içeren VOD içerik oynatması gerekiyorsa aşağıdakileri yapmanız gerekir:
- VOD test akışı için
CMS ID
veVideo ID
ekleyin. ImaServerSideAdInsertionUriBuilder()
işlevini kullanarak bir SSAI VOD URI'si oluşturun.- Bu yeni URI'yı oynatıcınızın medya öğesi olarak kullanın.
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); }
İşte bu kadar. Şu anda ExoPlayer IMA uzantısıyla bir medya akışı istiyorsunuz ve oynatıyorsunuz. Kodun tamamı için GitHub'daki Android DAI örneklerine göz atın.