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

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

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 اللغة.

ملاحظة: تتوافق حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية مع لغة Kotlin. ومع ذلك، فإن المثال التي نتناولها في هذا الدليل وتستخدم 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 (المستوى 30 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث من نظام التشغيل Android، تتطلّب إصدارات حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية إعلان صريح عن نية فتح الويب . يُرجى إضافة المقتطف التالي إلى ملف البيان في تطبيقك لتفعيل هذه الميزة. نسبة النقر إلى الظهور للإعلان (ينقر المستخدمون على زر مزيد من المعلومات).

  <?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>

إضافة معلمات ساحة المشاركات

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

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

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

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

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

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

أنشئ ثابت 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).

DAI في "مدير إعلانات Google" هو مثال على SSAI.
تم تصميم تنفيذ إضافة ExoPlayer لإعلانات الوسائط التفاعلية في هذا الدليل بشكل فعّال. تحديدًا باستخدام "إدراج إعلان ديناميكي" في "مدير إعلانات Google" تتضمّن إضافات إعلانات الوسائط التفاعلية في 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);
  }
}

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

أضِف طريقة لتحرير المشغّل بالتسلسل التالي:

يجب ضبط القيم المرجعية للّاعب على قيمة فارغة وتحرير موارد اللاعب.
حرر حالة 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 للحصول على الرمز الكامل.

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

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

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

إدراج إضافة إعلانات الوسائط التفاعلية (IMA) من ExoPlayer إلى مشروعك

app/build.gradle

app/src/main/AndroidManifest.xml

إضافة نماذج بيانات الغرض

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

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

إضافة معلمات ساحة المشاركات

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

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