ExoPlayer هو مشغّل وسائط على مستوى التطبيق في نظام Android. ويوضّح هذا الدليل كيفية استخدام إضافة إعلانات الوسائط التفاعلية في ExoPlayer التي تلي حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية، لطلب بث وسائط وتشغيلها يحتوي على إعلانات ومحتوى.
إليك بعض مزايا الإضافة:
- تبسيط الرمز اللازم لدمج إعلانات الوسائط التفاعلية مع الميزات
- تقليل وقت التطوير اللازم للتحديث إلى الإصدارات الجديدة من إعلانات الوسائط التفاعلية
تتوافق إضافة إعلانات الوسائط التفاعلية (IMA) من ExoPlayer مع بروتوكولات البث HLS وDASH. إليك ملخص:
إتاحة بث إضافات ExoPlayer-IMA | ||
---|---|---|
أحداث بث مباشر | عمليات بث الفيديوهات عند الطلب | |
HLS | ||
DASH |
تتوفّر أحداث البث المباشر المستندة إلى DASH على الإصدار 1.1.0 من ExoPlayer-IMA والإصدارات الأحدث.
يستند هذا الدليل إلى دليل ExoPlayer، ويوضّح
كيفية إنشاء تطبيق كامل ودمج الإضافة. راجِع
ExoPlayerExample
من
GitHub للاطّلاع على مثال مع
نموذج كامل للتطبيق.
المتطلّبات الأساسية
- استوديو Android
- الإصدار 1.0.0 من نظام التشغيل AndroidX Media3 ExoPlayer أو الإصدارات الأحدث لدعم "إدراج إعلان ديناميكي" (DAI).
إنشاء مشروع جديد على "استوديو Android"
لإنشاء مشروع على "استوديو Android"، يجب إكمال الخطوات التالية:
- شغِّل "استوديو Android".
- انقر على بدء مشروع جديد على "استوديو Android".
- في صفحة اختيار مشروعك، اختَر النموذج ما مِن نشاط.
- انقر على التالي.
في صفحة إعداد مشروعك، أدخِل اسمًا لمشروعك واختَر Java للّغة.
انقر على إنهاء.
إدراج إضافة إعلانات الوسائط التفاعلية (IMA) من ExoPlayer إلى مشروعك
أضِف عمليات استيراد للإضافة إلى الملف build.gradle على مستوى التطبيق
في القسم dependencies
.
اضبط تطبيقك على multidex وفعِّله. وهذا ضروري بسبب حجم الإضافة، وهو مطلوب للتطبيقات التي تم ضبط minSdkVersion
على Android 4.4W (مستوى واجهة برمجة التطبيقات
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' }
أضِف أذونات المستخدمين التي تتطلّبها حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية لطلب الإعلانات:
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>
إضافة نماذج بيانات الغرض
إذا كان تطبيقك يستهدف الإصدار 11 من نظام التشغيل Android (المستوى 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>
إضافة معلمات ساحة المشاركات
راجِع صفحة نموذج بث الوسائط التفاعلية للاطّلاع على عيّنات من مواد عرض مصدر البيانات من أجل اختبار مشروعك. اطّلِع أيضًا على قسم "مدير إعلانات Google" حول "إدراج إعلان ديناميكي" للحصول على معلومات حول إعداد أحداث البث الخاصة بك.
توضّح هذه الخطوة عملية إعداد البث المباشر، إلا أنّ إضافة ExoPlayer لإعلانات الوسائط التفاعلية تتيح أيضًا أحداث البث المباشر عند الطلب باستخدام DAI. اطّلِع على خطوة بث الفيديوهات عند الطلب لمعرفة التغييرات التي يحتاجها تطبيقك إلى معالجة عمليات بث الفيديوهات عند الطلب.
استيراد إضافة إعلانات الوسائط التفاعلية في ExoPlayer
أضف عبارات الاستيراد للإضافة ExoPlayer.
أضِف المتغيّرات الخاصة التالية إلى MyActivity.java
:
PlayerView
ExoPlayer
ImaServerSideAdInsertionMediaSource.AdsLoader
ImaServerSideAdInsertionMediaSource.AdsLoader.State
أضِف مفتاح مادة عرض Big Buck Bunny (Live) للبث 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
.
ويمكنك أيضًا تفعيل ميزة Multidex إذا كان ذلك مطلوبًا من خلال عدد طرق التطبيق و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.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 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 لإعلانات الوسائط التفاعلية. يمكنك إلقاء نظرة على نماذج "إدراج إعلان ديناميكي" في نظام التشغيل Android على GitHub للاطّلاع على الرمز البرمجي الكامل.