بدء استخدام إضافة ExoPlayer لإعلانات الوسائط التفاعلية

‫ExoPlayer هو مشغّل وسائط لنظام Android. يوضّح لك هذا الدليل كيفية استخدام إضافة ExoPlayer IMA. يستخدم هذا الامتداد حزمة تطوير البرامج لـ "الإعلانات الديناميكية أثناء عرض الفيديو" من "إعلانات الوسائط التفاعلية" لطلب وتشغيل بث الوسائط الذي يتضمّن كلاً من الإعلانات والمحتوى.

في ما يلي قائمة بمزايا الإضافة:

• تبسّط الرمز البرمجي اللازم لدمج ميزات IMA.
• يقلّل من الوقت المطلوب للتحديث إلى إصدارات IMA الجديدة.

تتوافق إضافة IMA في ExoPlayer مع بروتوكولَي البث المباشر HLS وDASH. في ما يلي ملخّص:

إتاحة بث ExoPlayer-IMA
	بث مباشر	فيديوهات عند الطلب
HLS
DASH

يتوافق الإصدار 1.1.0 من ExoPlayer-IMA والإصدارات الأحدث مع بث المحتوى المباشر بتنسيق DASH.

يستخدم هذا الدليل دليل ExoPlayer لمساعدتك في إنشاء تطبيق كامل ودمج الإضافة. للحصول على نموذج تطبيق كامل، يُرجى الاطّلاع على ExoPlayerExample على GitHub.

ملاحظة مهمة: تتطلّب إضافة ExoPlayer IMA توفّر ExoPlayer. إذا كنت تفضّل استخدام مشغّل مختلف، اتّبِع دليل البدء لدمج حزمة تطوير البرامج (SDK) لخدمة "إعلانات الوسائط الرقمية المباشرة" من "إعلانات الوسائط التفاعلية" في تطبيقك.

المتطلبات الأساسية

• استوديو Android
• الإصدار 1.0.0 من AndroidX Media3 ExoPlayer أو إصدار أحدث لتوفير دعم "الإعلانات الديناميكية أثناء البث"

إنشاء مشروع جديد في "استوديو Android"

لإنشاء مشروعك على "استوديو Android"، اتّبِع الخطوات التالية:

1. ابدأ "استوديو Android".
2. انقر على بدء مشروع جديد في "استوديو Android".
3. في صفحة اختيار مشروعك، اختَر نموذج لا يوجد نشاط.
4. انقر على التالي.
5. في صفحة إعداد مشروعك، أدخِل اسمًا لمشروعك واختَر Java كلغة. ملاحظة: تعمل حزمة تطوير البرامج (SDK) لخدمة "الإعلانات الديناميكية أثناء عرض الفيديو" من "إعلانات الوسائط التفاعلية" مع Kotlin، ولكن يستخدم هذا الدليل أمثلة Java.

• انقر على إنهاء.

إضافة إضافة ExoPlayer IMA إلى مشروعك

لإضافة إضافة ExoPlayer IMA، اتّبِع الخطوات التالية:

1. أدرِج عمليات الاستيراد التالية في قسم dependencies من ملف build.gradle الخاص بتطبيقك:

   dependencies {
       def media3_version = "1.8.0"
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
       implementation 'androidx.appcompat:appcompat:1.7.1'
       implementation "androidx.media3:media3-ui:$media3_version"
       implementation "androidx.media3:media3-exoplayer:$media3_version"
       implementation "androidx.media3:media3-exoplayer-hls:$media3_version"
       implementation "androidx.media3:media3-exoplayer-dash:$media3_version"
   
       // The library adds the IMA ExoPlayer integration for ads.
       implementation "androidx.media3:media3-exoplayer-ima:$media3_version"
   }
   build.gradle
   

2. أضِف أذونات المستخدم التي تحتاج إليها حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (DAI) من أجل طلب الإعلانات:

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   AndroidManifest.xml
   

إعداد واجهة مستخدم ExoPlayer

لإعداد واجهة مستخدم ExoPlayer، اتّبِع الخطوات التالية:

1. أنشئ العنصر PlayerView لـ ExoPlayer.

2. غيِّر طريقة العرض androidx.constraintlayout.widget.ConstraintLayout إلى طريقة العرض LinearLayout، كما هو مقترَح في إضافة ExoPlayer IMA:

   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools"
       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:fitsSystemWindows="true"
           android:layout_width="match_parent"
           android:layout_height="wrap_content" />
   
       <!-- UI element for viewing SDK event log -->
       <TextView
           android:id="@+id/logText"
           android:gravity="bottom"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:maxLines="100"
           android:scrollbars="vertical"
           android:textSize="@dimen/font_size">
       </TextView>
   
   </LinearLayout>
   activity_my.xml
   

إضافة مَعلمات البث

يمكنك الاطّلاع على صفحة عيّنة البث في IMA للحصول على مواد عرض عيّنة البث لاختبار مشروعك. لإعداد قنوات البث الخاصة بك، يُرجى الاطّلاع على قسم "مدير إعلانات Google" حول "الإعلانات الديناميكية أثناء البث".

تتيح لك هذه الخطوة إعداد بث مباشر. تتيح إضافة IMA في ExoPlayer أيضًا إمكانية عرض إعلانات ديناميكية في الفيديوهات عند الطلب. لمعرفة التغييرات التي يجب إجراؤها في تطبيقك لبث فيديوهات عند الطلب، راجِع خطوة بث فيديوهات عند الطلب.

استيراد إضافة ExoPlayer IMA

1. أضِف عبارات الاستيراد التالية لإضافة ExoPlayer:

   import static androidx.media3.common.C.CONTENT_TYPE_HLS;
   
   import android.annotation.SuppressLint;
   import android.app.Activity;
   import android.net.Uri;
   import android.os.Bundle;
   import android.text.method.ScrollingMovementMethod;
   import android.util.Log;
   import android.widget.TextView;
   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.ui.PlayerView;
   import com.google.ads.interactivemedia.v3.api.AdEvent;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
   import java.util.HashMap;
   import java.util.Map;
   MyActivity.java
   

2. في MyActivity.java، أضِف المتغيّرات الخاصة التالية:

   • PlayerView
   • ExoPlayer
   • ImaServerSideAdInsertionMediaSource.AdsLoader
   • ImaServerSideAdInsertionMediaSource.AdsLoader.State

   للاختبار باستخدام بث HLS Big Buck Bunny (Live)، أضِف مفتاح مادة العرض. يمكنك العثور على المزيد من الفيديوهات التجريبية على صفحة الفيديوهات التجريبية في IMA.

3. أنشئ ثابت KEY_ADS_LOADER_STATE لحفظ حالة AdsLoader واستردادها:

   /** Main Activity. */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   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 LOG_TAG = "ImaExoPlayerExample";
   
     private PlayerView playerView;
     private TextView logText;
     private ExoPlayer player;
     private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
     private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;
     private ImaSdkSettings imaSdkSettings;
   MyActivity.java
   

إنشاء مثيل adsLoader

تجاوز طريقة onCreate ابحث في هذا الملف عن PlayerView وتحقّق من وجود AdsLoader.State محفوظة. يمكنك استخدام هذه الحالة عند تهيئة العنصر adsLoader.

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_my);

  // Initialize the IMA SDK as early as possible when the app starts. If your app already
  // overrides Application.onCreate(), call this method inside the onCreate() method.
  // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
  ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());

  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);
    }
  }
}

private ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    // Set any IMA SDK settings here.
  }
  return imaSdkSettings;
}
MyActivity.java

ملاحظة مهمة: لتحسين أوقات تحميل IMA، استخدِم طريقة ImaSdkFactory.initialize() في أقرب وقت ممكن في دورة حياة التطبيق. يؤدي استدعاء الطريقة مبكرًا إلى زيادة الوقت المتاح لـ IMA لتحميل الموارد اللازمة قبل طلب البث الأول. يقبل استدعاء الإجراء ImaSdkFactory.initialize() مثيلاً من ImaSdkSettings. احرص على استخدام قيم الإعدادات نفسها هنا وعند إنشاء مثيل AdsLoader. يستخدم هذا المثال طريقة المساعد getImaSdkSettings() للتأكّد من أنّ قيم الإعدادات متطابقة. لمزيد من المعلومات، يُرجى الاطّلاع على دليل تحسين مدّة تحميل IMA>.

إضافة طرق لتهيئة المشغّل

أضِف طريقة لإعداد المشغّل. يجب أن تنفّذ هذه الطريقة ما يلي:

• أنشئ مثيلاً من AdsLoader.
• أنشئ ExoPlayer.
• أنشئ MediaItem باستخدام مفتاح مادة عرض البث المباشر.
• اضبط MediaItem للمشغّل.

// Create a server side ad insertion (SSAI) AdsLoader.
private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
      new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

  // Attempts to set the AdsLoader state if available from a previous session.
  if (adsLoaderState != null) {
    adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
  }

  return adsLoaderBuilder
      .setAdEventListener(buildAdEventListener())
      .setImaSdkSettings(getImaSdkSettings())
      .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 a SimpleExoPlayer and set it as the player for content and ads.
  player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
  playerView.setPlayer(player);
  adsLoader.setPlayer(player);

  // Create the MediaItem to play, specifying the stream URI.
  Uri ssaiUri = buildLiveStreamUri(SAMPLE_ASSET_KEY, CONTENT_TYPE_HLS);
  MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiUri);

  // 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);
}

/**
 * Builds an IMA SSAI live stream URI for the given asset key and format.
 *
 * @param assetKey The asset key of the live stream.
 * @param format The format of the live stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the live stream.
 */
public Uri buildLiveStreamUri(String assetKey, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setAssetKey(assetKey)
      .setFormat(format)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

ملاحظة: يستخدم هذا القسم طرقًا بأسماء تشير إلى مفاهيم إدراج الإعلانات من جهة الخادم (SSAI).

• ‫Google Ad Manager DAI هو مثال على SSAI.
• تعمل إضافة ExoPlayer IMA في هذا الدليل تحديدًا مع ميزة "الإعلانات الديناميكية أثناء البث" في "مدير إعلانات Google". يتوافق إضافة IMA في ExoPlayer أيضًا مع حلول مختلفة لإدراج الإعلانات من جهة الخادم.

إضافة طريقة لإطلاق اللاعب

أضِف طريقة لإيقاف المشغّل. يجب أن تنفّذ هذه الطريقة الإجراءات التالية بالتسلسل:

• اضبط مراجع المشغّل على القيمة الخالية وحرِّر موارد المشغّل.
• إلغاء حالة adsLoader

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();
}
MyActivity.java

التعامل مع أحداث اللاعب

للتعامل مع أحداث اللاعبين، أنشئ استدعاءات لأحداث مراحل نشاط التطبيق لإدارة تشغيل البث.

بالنسبة إلى المستوى 24 من واجهة برمجة التطبيقات Android API والإصدارات الأحدث، استخدِم الطرق التالية:

• onStart()
• onStop()

بالنسبة إلى مستويات واجهة برمجة التطبيقات Android الأقل من 24، استخدِم الطرق التالية:

• onResume()
• onPause()

يتم ربط الطريقتَين onStart() وonResume() بـ playerView.onResume()، بينما يتم ربط الطريقتَين onStop() وonPause() بـ playerView.onPause().

نقطة أساسية: يتوافق هذا المثال مع الإصدار 24 من حزمة تطوير البرامج (SDK) لنظام التشغيل Android والإصدارات الأقدم. استخدِم onStart()/onStop() للإصدار 24 أو الإصدارات الأحدث من حزمة تطوير البرامج (SDK) لنظام التشغيل Android، واستخدِم onResume()/onPause() للإصدارات الأقدم من الإصدار 24.

تستخدِم هذه الخطوة أيضًا حدث onSaveInstanceState() لحفظ adsLoaderState.

@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());
  }
}
MyActivity.java

إعداد بث الفيديو عند الطلب (اختياري)

إذا كان تطبيقك يحتاج إلى تشغيل محتوى فيديو عند الطلب مع إعلانات، اتّبِع الخطوات التالية:

1. أضِف CMS ID وVideo ID لتدفق VOD. للاختبار، استخدِم مَعلمات البث التالية:
   • معرّف نظام إدارة المحتوى: "2548831"
   • معرّف الفيديو: "tears-of-steel"

2. أنشئ معرّف الموارد المنتظم (URI) لفيديو عند الطلب (VOD) باستخدام ميزة "إدراج الإعلانات من جهة الخادم" (SSAI) باستخدام الطريقة ImaServerSideAdInsertionUriBuilder():

   /**
    * Builds an IMA SSAI VOD stream URI for the given CMS ID, video ID, and format.
    *
    * @param cmsId The CMS ID of the VOD stream.
    * @param videoId The video ID of the VOD stream.
    * @param format The format of the VOD stream request, either {@code CONTENT_TYPE_HLS} or {@code
    *     CONTENT_TYPE_DASH}.
    * @return The URI of the VOD stream.
    */
   public Uri buildVodStreamUri(String cmsId, String videoId, int format) {
     Map<String, String> adTagParams = new HashMap<String, String>();
     // Update the adTagParams map with any parameters.
     // For more information, see https://support.google.com/admanager/answer/7320899
   
     return new ImaServerSideAdInsertionUriBuilder()
         .setContentSourceId(cmsId)
         .setVideoId(videoId)
         .setFormat(format)
         .setAdTagParameters(adTagParams)
         .build();
   }
   MyActivity.java
   

3. اضبط معرّف الموارد الموحّد الجديد لبث الفيديو عند الطلب كعنصر وسائط في المشغّل باستخدام طريقة MediaItem.fromUri().

في حال نجاح العملية، يمكنك طلب بث وسائط وتشغيله باستخدام إضافة ExoPlayer IMA. للاطّلاع على المثال الكامل، يُرجى الرجوع إلى نماذج "الإعلانات الديناميكية أثناء البث" على Android على GitHub.