ExoPlayer یک پخش کننده رسانه سطح برنامه برای اندروید است. این راهنما نشان میدهد که چگونه میتوانید از افزونه ExoPlayer IMA ، که IMA DAI SDK را میپیچد، برای درخواست و پخش یک جریان رسانه با تبلیغات و محتوا استفاده کنید.
در اینجا برخی از مزایای افزونه آورده شده است:
- کد مورد نیاز برای ادغام IMA با ویژگی ها را ساده می کند.
- زمان توسعه مورد نیاز برای به روز رسانی به نسخه های جدید IMA را کاهش می دهد.
افزونه ExoPlayer IMA از پروتکل های جریان HLS و DASH پشتیبانی می کند. در اینجا خلاصه ای وجود دارد:
پشتیبانی از جریان برنامه افزودنی ExoPlayer-IMA | ||
---|---|---|
پخش زنده | جریان های VOD | |
HLS | ||
داش |
پخشهای زنده DASH در ExoPlayer-IMA نسخه 1.1.0+ پشتیبانی میشوند.
این راهنما بر اساس راهنمای ExoPlayer است و نحوه ایجاد یک برنامه کامل و ادغام برنامه افزودنی را نشان می دهد. برای مثال با یک نمونه برنامه کامل، ExoPlayerExample
از GitHub ببینید.
پیش نیازها
- اندروید استودیو
- AndroidX Media3 ExoPlayer نسخه 1.0.0 یا بالاتر برای پشتیبانی از DAI.
یک پروژه Android Studio جدید ایجاد کنید
برای ایجاد پروژه Android Studio خود، مراحل زیر را انجام دهید:
- Android Studio را راه اندازی کنید.
- شروع پروژه جدید Android Studio را انتخاب کنید.
- در صفحه Choose your project ، الگوی No Activity را انتخاب کنید.
- روی Next کلیک کنید.
در صفحه Configure your project ، نام پروژه خود را گذاشته و جاوا را برای زبان انتخاب کنید.
روی Finish کلیک کنید.
پسوند ExoPlayer IMA را به پروژه خود اضافه کنید
در بخش dependencies
، واردات برای پسوند را به فایل build.gradle در سطح برنامه اضافه کنید.
برنامه خود را روی multidex پیکربندی و فعال کنید. این به دلیل اندازه برنامه افزودنی ضروری است و برای برنامههایی با minSdkVersion
تنظیم شده روی Android 4.4W (سطح API 20) یا پایینتر لازم است.
در اینجا یک مثال است:
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' }
مجوزهای کاربر مورد نیاز IMA DAI SDK را برای درخواست تبلیغات اضافه کنید:
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>
اعلامیه های قصد را اضافه کنید
اگر برنامه شما Android 11 (سطح API 30) یا بالاتر را هدف قرار میدهد، نسخههای فعلی و اخیر IMA DAI SDK به یک اعلامیه صریح از قصد برای باز کردن پیوندهای وب نیاز دارند. قطعه زیر را به فایل مانیفست برنامه خود اضافه کنید تا امکان کلیک روی تبلیغات فعال شود (کاربران روی دکمه بیشتر بدانید ).
<?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 را تنظیم کنید
شی PlayerView
را برای استفاده توسط ExoPlayer ایجاد کنید.
androidx.constraintlayout.widget.ConstraintLayout
را به LinearLayout
تغییر دهید، که برای برنامه افزودنی ExoPlayer IMA توصیه می شود.
در اینجا یک مثال است:
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>
پارامترهای جریان خود را اضافه کنید
برای آزمایش پروژه خود، صفحه جریان نمونه IMA را برای نمونه دارایی های جریان ببینید. همچنین برای اطلاعات در مورد تنظیم جریان های خود به بخش Ad Manager در DAI مراجعه کنید.
این مرحله راهاندازی یک جریان زنده را نشان میدهد، اما افزونه ExoPlayer IMA از جریانهای DAI VOD نیز پشتیبانی میکند. مرحله پخشهای ویدیوی درخواستی (VOD) را ببینید تا ببینید برنامه شما برای مدیریت جریانهای VOD به چه تغییراتی نیاز دارد.
پسوند ExoPlayer IMA را وارد کنید
دستورهای import را برای پسوند ExoPlayer اضافه کنید.
متغیرهای خصوصی زیر را به MyActivity.java
اضافه کنید:
-
PlayerView
-
ExoPlayer
-
ImaServerSideAdInsertionMediaSource.AdsLoader
-
ImaServerSideAdInsertionMediaSource.AdsLoader.State
کلید دارایی جریان HLS Big Buck Bunny (زنده) را برای آزمایش با این جریان اضافه کنید. جریانهای بیشتری برای آزمایش در صفحه جریان نمونه IMA موجود است.
برای ذخیره و بازیابی حالت AdsLoader
یک ثابت KEY_ADS_LOADER_STATE
ایجاد کنید.
در اینجا یک مثال است:
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
ایجاد کنید
روش onCreate
را بازنویسی کنید تا PlayerView
را پیدا کنید و یک AdsLoader.State
ذخیره شده را بررسی کنید، که می تواند هنگام شروع شی adsLoader
استفاده شود.
همچنین، در صورت نیاز به تعداد متد برنامه و minSdkVersion
multidex را فعال کنید (همانطور که در مرحله 2 توضیح داده شد).
در اینجا یک مثال است:
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); } } } }
روش هایی را برای مقداردهی اولیه پخش کننده اضافه کنید
یک روش برای مقداردهی اولیه پخش کننده اضافه کنید و کارهای زیر را انجام دهید:
- یک نمونه
AdsLoader
ایجاد کنید. -
ExoPlayer
را ایجاد کنید. - با کلید دارایی پخش زنده یک
MediaItem
ایجاد کنید. -
MediaItem
را روی پخش کننده خود تنظیم کنید.
در اینجا یک مثال است:
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); } }
روشی برای آزاد کردن پخش کننده اضافه کنید
یک روش برای آزاد کردن پخش کننده در این دنباله اضافه کنید:
- ارجاعات پخش کننده را صفر تنظیم کنید و منابع پخش کننده را آزاد کنید.
- وضعیت
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(); }
رویدادهای بازیکن را مدیریت کنید
در نهایت، برای رویدادهای چرخه حیات فعالیت، تماسهایی ایجاد کنید تا پخش جریانی را مدیریت کنید.
برای پشتیبانی از Android SDK نسخه 24+:
برای پشتیبانی از نسخههای Android SDK کمتر از ۲۴: - onResume()
- onPause()
onStart()
و onResume()
به playerView.onResume()
و onStop()
و onPause()
به playerView.onPause()
نگاشت.
این مرحله همچنین از رویداد onSaveInstanceState()
برای ذخیره 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()); } } ... }
تنظیم جریان VOD (اختیاری)
اگر برنامه شما برای پخش محتوای VOD با تبلیغات مورد نیاز است، باید موارد زیر را انجام دهید:
- یک
CMS ID
وVideo ID
برای جریان آزمایش VOD اضافه کنید. - یک URI SSAI VOD با استفاده از
ImaServerSideAdInsertionUriBuilder()
ایجاد کنید. - از این URI جدید به عنوان آیتم رسانه پخش کننده خود استفاده کنید.
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); }
همین! اکنون در حال درخواست و پخش یک جریان رسانه با پسوند ExoPlayer IMA هستید. برای دریافت کد کامل به نمونههای DAI اندروید در GitHub نگاهی بیندازید.