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

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

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

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

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

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

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

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

ملاحظة مهمة: تتطلّب إضافة ExoPlayer IMA مشغّل ExoPlayer. إذا كنت تفضّل مشغّلاً مختلفًا، اتّبِع دليل البدء لدمج حزمة IMA DAI SDK في تطبيقك.

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

• استوديو Android
• الإصدار 1.0.0 من AndroidX Media3 ExoPlayer أو إصدار أحدث لتوفير الدعم لـ DAI

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

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

1. ابدأ "استوديو Android".
2. انقر على Start a new Android Studio project (بدء مشروع جديد في "استوديو Android").
3. في صفحة Choose your project (اختيار مشروعك) ، اختَر نموذج No Activity (بدون نشاط).
4. انقر على التالي.
5. في صفحة Configure your project (إعداد مشروعك) ، امنح مشروعك اسمًا واختَر Java كلغة. ملاحظة: تعمل حزمة IMA DAI SDK مع Kotlin، ولكن يستخدم هذا الدليل أمثلة Java.

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

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

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

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

   dependencies {
       def media3_version = "1.9.1"
       coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.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. أضِف أذونات المستخدم التي تحتاج إليها حزمة IMA DAI SDK لطلب الإعلانات:

   <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" في DAI.

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

استيراد إضافة 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 DAI هو مثال على SSAI.
• تعمل إضافة ExoPlayer IMA في هذا الدليل تحديدًا مع إدراج إعلان ديناميكي في Ad Manager. تتوافق إضافة ExoPlayer IMA أيضًا مع حلول SSAI المختلفة.

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

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

• اضبط مراجع المشغّل على null وأوقِف موارد المشغّل.
• أوقِف حالة 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 والإصدارات الأحدث، استخدِم الطريقتَين التاليتَين:

• onStart()
• onStop()

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

• onResume()
• onPause()

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

**ملاحظة مهمة:** يتوافق هذا المثال مع الإصدار 24 من حزمة Android SDK والإصدارات الأقدم. استخدِم onStart()/onStop() للإصدار 24 من حزمة Android SDK والإصدارات الأحدث، و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 لمصدر بيانات الفيديوهات عند الطلب. للاختبار، استخدِم مَعلمات مصدر البيانات التالية:
   • CMS ID: "2548831"
   • Video ID: "tears-of-steel"

2. أنشِئ معرّف URI للفيديوهات عند الطلب في 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. اضبط معرّف URI الجديد لمصدر بيانات الفيديوهات عند الطلب كعنصر الوسائط لمشغّلك باستخدام طريقة MediaItem.fromUri():

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