ExoPlayer هو مشغّل وسائط على مستوى التطبيق لنظام التشغيل Android. يوضّح هذا الدليل كيفية استخدام إضافة ExoPlayer لإعلانات الوسائط التفاعلية، التي تضم حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية لنظام التشغيل Android، لطلب بث وسائط وتشغيله مع كلّ من الإعلانات والمحتوى.
إليك بعض مزايا الإضافة:
- تبسيط الرمز اللازم لدمج إعلانات الوسائط التفاعلية مع الميزات.
- تقليل وقت التطوير اللازم للتحديث إلى الإصدارات الجديدة من إعلانات الوسائط التفاعلية (IMA).
تتوافق إضافة ExoPlayer لإعلانات الوسائط التفاعلية مع بروتوكولات البث HLS وDASH. إليك ملخص:
إتاحة بث إضافة ExoPlayer-IMA | ||
---|---|---|
أحداث بث مباشر | مجموعات بث عند الطلب | |
HLS | ||
بروتوكول DASH |
تتوفّر أحداث البث المباشر بتنسيق DASH على ExoPlayer-IMA الإصدار 1.1.0 أو الإصدارات الأحدث.
يستند هذا الدليل إلى دليل ExoPlayer، ويعرض كيفية إنشاء تطبيق كامل ودمج الإضافة. اطّلع على ExoPlayerExample
من GitHub للحصول على مثال مع نموذج تطبيق كامل.
المتطلبات الأساسية
- استوديو Android
- الإصدار 1.0.0 من AndroidX Media3 ExoPlayer أو إصدار أحدث لدعم ميزة DAI.
إنشاء مشروع جديد على "استوديو Android"
لإنشاء مشروعك على "استوديو Android"، يجب إكمال الخطوات التالية:
- شغِّل Android Studio.
- اختَر بدء مشروع جديد على "استوديو Android".
- في صفحة اختيار مشروعك، حدِّد النموذج لا نشاط.
- انقر على التالي.
في صفحة Configure your project (إعداد مشروعك)، أدخِل اسمًا لمشروعك واختَر Java لللغة.
انقر على إنهاء.
إدراج إضافة ExoPlayer لإعلانات الوسائط التفاعلية في مشروعك
أضِف عمليات استيراد للإضافة إلى ملف build.gradle على مستوى التطبيق في القسم dependencies
.
اضبط تطبيقك على
multidex وفعِّله. يُعدّ هذا الإجراء ضروريًا بسبب حجم الإضافة، وهو مطلوب للتطبيقات التي تم ضبط minSdkVersion
فيها على Android 4.4W (المستوى 20 من واجهة برمجة التطبيقات) أو أقل.
وفي ما يلي مثال لذلك:
app/build.gradle
android { ... defaultConfig { applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp" minSdkVersion 19 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' }
أضِف أذونات المستخدم التي تتطلّبها حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لطلب الإعلانات:
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 SDK --> <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> ... </manifest>
إضافة بيانات الأهداف
إذا كان تطبيقك يستهدف الإصدار Android 11 (المستوى 30 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، تتطلّب الإصدارات الحالية والحديثة من حزمة تطوير البرامج لإعلانات الوسائط التفاعلية تقديم بيان صريح عن النية في فتح روابط الويب. أضِف المقتطف التالي إلى ملف البيان لتطبيقك لتفعيل نسب النقر إلى الظهور على الإعلان (أي ينقر المستخدمون على زر مزيد من المعلومات).
<?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.
وفي ما يلي مثال لذلك:
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>
إضافة مَعلمات البث
راجِع صفحة نموذج بث إعلانات الوسائط التفاعلية للاطّلاع على نماذج مواد عرض البث لاختبار مشروعك. يمكنك أيضًا مراجعة قسم "مدير الإعلانات" حول إدراج إعلان ديناميكي للحصول على معلومات حول إعداد أحداث البث الخاصة بك.
توضّح هذه الخطوة إعداد بث مباشر، إلا أنّ إضافة إعلانات الوسائط التفاعلية في ExoPlayer تتيح أيضًا عمليات بث الفيديوهات عند الطلب التي تستخدم ميزة DAI. يمكنك الاطّلاع على خطوات بث الفيديو عند الطلب (VOD) لمعرفة التغييرات التي يحتاجها تطبيقك في معالجة عمليات بث الفيديو عند الطلب.
استيراد إضافة ExoPlayer IMA
أضِف عبارات الاستيراد لإضافة ExoPlayer.
أضِف المتغيّرات الخاصة التالية إلى MyActivity.java
:
PlayerView
ExoPlayer
ImaServerSideAdInsertionMediaSource.AdsLoader
ImaServerSideAdInsertionMediaSource.AdsLoader.State
أضِف مفتاح مادة العرض الخاص ببث Big Buck Bunny (البث المباشر) HLS لاختباره من خلال هذا البث. يمكنك اختبار المزيد من أحداث البث على صفحة نموذج البث في إعلانات الوسائط التفاعلية.
أنشئ ثابت KEY_ADS_LOADER_STATE
لحفظ حالة AdsLoader
واستردادها.
وفي ما يلي مثال لذلك:
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
(على النحو الموضَّح في
الخطوة 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.CREATOR.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(); }
التعامل مع أحداث اللاعبين
وأخيرًا، يمكنك إنشاء استدعاءات لأحداث مراحل النشاط لمعالجة إعادة تشغيل البث.
لدعم الإصدار 24 من حزمة تطوير البرامج (SDK) لنظام التشغيل Android أو الإصدارات الأحدث:
لإتاحة إصدارات حزمة تطوير البرامج (SDK) لنظام التشغيل Android الأقل من 24:
- 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()); } } ... }
إعداد بث فيديو عند الطلب (اختياري)
إذا كان مطلوبًا من تطبيقك تشغيل محتوى فيديو عند الطلب مع إعلانات، عليك اتّباع الخطوات التالية:
- يُرجى إضافة
CMS ID
وVideo ID
لبثّ المحتوى التجريبي ضمن الفيديو المسجّل. - أنشِئ معرّف الموارد المنتظم (URI) لـ SSAI باستخدام "
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 = "2528370"; 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. يمكنك إلقاء نظرة على نماذج DAI لنظام التشغيل Android على GitHub للاطّلاع على الرمز البرمجي الكامل.