تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

إتاحة بث إضافة ExoPlayer-IMA
	بث مباشر	أحداث الفيديوهات المسجّلة
HLS
DASH

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

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

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

Android Studio
الإصدار 1.0.0 من AndroidX Media3 ExoPlayer أو إصدار أحدث لتفعيل ميزة DAI

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

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

ابدأ "استوديو Android".
اختَر بدء مشروع جديد في "استوديو Android".
في صفحة اختيار مشروعك، اختَر نموذج بدون نشاط.
انقر على التالي.
في صفحة Configure your project (ضبط مشروعك)، أدخِل اسمًا لمشروعك واختَر Java للّغة.

ملاحظة: تتوافق حزمة تطوير البرامج (SDK) لعرض الإعلانات الديناميكية أثناء التشغيل في إعلانات الوسائط التفاعلية مع لغة Kotlin. ومع ذلك، يستخدم المثال الموضَّح في هذا الدليل لغة Java.
انقر على إنهاء.

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

أضِف عمليات استيراد للإضافة إلى ملف 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'
}

أضِف أذونات المستخدمين المطلوبة من قِبل حزمة تطوير البرامج (SDK) لعرض الإعلانات الديناميكية في "إعلانات الوسائط التفاعلية" لطلب الإعلانات:

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 لواجهة برمجة التطبيقات) أو إصدارًا أحدث، تتطلّب الإصدارات الحالية والحديثة من حزمة تطوير البرامج (SDK) لعرض الإعلانات الديناميكية على الويب من IMA بيانًا صريحًا عن نية فتح روابط الويب. أضِف المقتطف التالي إلى ملف بيان تطبيقك لتفعيل النقرات على الإعلانات (المستخدمون الذين ينقرون على الزر مزيد من المعلومات).

  <?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، وهو الخيار المُقترَح لإضافات IMA في 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 للحصول على مواد عرض نموذج البث لاختبار مشروعك. اطّلِع أيضًا على قسم "مدير إعلانات Google" حول الإعلانات الديناميكية أثناء عرض الفيديو للحصول على معلومات عن إعداد عمليات البث الخاصة بك.

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

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

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

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

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

أنشئ ثابتًا من النوع 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 على المشغّل.

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

إدراج الإعلان الديناميكي في "مدير إعلانات Google" هو مثيل لميزة "إدراج الإعلانات الديناميكية أثناء عرض الفيديو".
تم تصميم عملية تنفيذ إضافة IMA في ExoPlayer في هذا الدليل للعمل مع ميزة "عرض الإعلانات أثناء التشغيل" في "مدير إعلانات Google". تتوافق أيضًا إضافات IMA في ExoPlayer مع عمليات SSAI الأخرى، مثل Google Cloud Platform، والتي لم يتم توضيحها في هذا الدليل.

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

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

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

أضِف طريقة لتحرير اللاعب في هذا التسلسل:

اضبط مراجع اللاعبين على القيمة null (قيمة فارغة) واطرَح موارد اللاعبين.
ارفع إصبعك عن حالة 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 لبث اختباري لفيديو عند الطلب.
أنشئ عنوان URL لفيديو عند الطلب في SSAI باستخدام ImaServerSideAdInsertionUriBuilder().
استخدِم عنوان URL الجديد هذا كعنصر وسائط للمشغّل.

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 IMA. اطّلِع على نماذج "الإعلانات الديناميكية أثناء عرض الفيديو" على Android على GitHub للاطّلاع على الرمز الكامل.

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

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

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

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

app/build.gradle

app/src/main/AndroidManifest.xml

إضافة بيانات النوايا

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

app/src/main/res/layout/activity_my.xml

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

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

app/src/main/java/com/example/project name/MyActivity.java

إنشاء مثيل adsLoader

app/src/main/java/com/example/project name/MyActivity.java

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

app/src/main/java/com/example/project name/MyActivity.java

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

app/src/main/java/com/example/project name/MyActivity.java

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

app/src/main/java/com/example/project name/MyActivity.java

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

app/src/main/java/com/example/project name/MyActivity.java

app/src/main/java/com/example/`project name`/MyActivity.java

إنشاء مثيل `adsLoader`

app/src/main/java/com/example/`project name`/MyActivity.java

app/src/main/java/com/example/`project name`/MyActivity.java

app/src/main/java/com/example/`project name`/MyActivity.java

app/src/main/java/com/example/`project name`/MyActivity.java

app/src/main/java/com/example/`project name`/MyActivity.java