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

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

إليك بعض مزايا الإضافة:

• تبسيط التعليمات البرمجية اللازمة لدمج إعلانات الوسائط التفاعلية مع الميزات.
• تقليل وقت التطوير اللازم للتحديث إلى الإصدارات الجديدة من إعلانات الوسائط التفاعلية (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 Studio.
• اختَر بدء مشروع جديد على "استوديو Android".
• في صفحة اختيار مشروعك، اختَر النموذج ما مِن نشاط.
• انقر على التالي.

• في صفحة Configure your project (إعداد مشروعك)، أدخِل اسمًا لمشروعك واختَر Java للغة.

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

تثبيت إضافة ExoPlayer لإعلانات الوسائط التفاعلية في مشروعك

أدرِج عمليات استيراد للإضافة في ملف build.gradle على مستوى التطبيق في القسم dependencies.

اضبط تطبيقك على multidex وفعِّله. هذا الإجراء ضروري لأنّ حجم الإضافة مطلوبة للتطبيقات التي تم ضبط minSdkVersion فيها على Android 4.4W (المستوى 20 لواجهة برمجة التطبيقات) أو أقل.

وفي ما يلي مثال لذلك:

app/build.grale

android {

  ...

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 19
      targetSdkVersion 31
      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>

إعداد واجهة مستخدم 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>

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

يمكنك الاطّلاع على صفحة نماذج مصادر إعلانات الوسائط التفاعلية للاطّلاع على مواد عرض نموذجية لمصادر البيانات من أجل اختبار مشروعك. راجع أيضًا قسم "مدير الإعلانات" حول "إدراج إعلان ديناميكي" للحصول على معلومات حول إعداد أحداث البث المباشر.

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

استيراد إضافة ExoPlayer لإعلانات الوسائط التفاعلية

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

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

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

أضِف مفتاح مادة عرض البث المباشر وفق بروتوكول HTTP (HLS) Big Buck Bunny (بث مباشر) لاختباره في هذا البث. يتوفر مزيد من أحداث البث المباشر للاختبار على صفحة نموذج البث في إعلانات الوسائط التفاعلية.

أنشِئ ثابت 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 أو الإصدارات الأحدث:

• onStart()
• onStop()

التوافق مع إصدارات حزمة تطوير البرامج (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());
    }
  }

  ...

}

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

إذا كان مطلوبًا في تطبيقك تشغيل محتوى فيديو عند الطلب مع إعلانات، عليك تنفيذ ما يلي:

1. يُرجى إضافة CMS ID وVideo ID لبثّ محتوى تجريبي عند الطلب.
2. يمكنك إنشاء معرّف موارد منتظم (URI) لـ SSAI VOD باستخدام السمة ImaServerSideAdInsertionUriBuilder().
3. يمكنك استخدام معرّف الموارد المنتظم (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. يمكنك الاطّلاع على نماذج Android DAI على GitHub للاطّلاع على الرمز الكامل.