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

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

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

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

نظرة عامة على IMA من جهة العميل

يتضمّن تنفيذ IMA من جهة العميل أربعة مكوّنات رئيسية لحزمة تطوير البرامج، وهي موضّحة في هذا الدليل:

AdDisplayContainer: عنصر حاوية يحدّد مواضع عرض عناصر واجهة مستخدِم الإعلان في IMA وقياس إمكانية العرض، بما في ذلك العرض النشط و القياس المفتوح.
AdsLoader: عنصر يطلب الإعلانات ويعالج الأحداث الواردة من استجابات طلبات الإعلانات. يجب إنشاء مثيل واحد فقط لتحميل الإعلانات، والذي يمكن إعادة استخدامه طوال مدة استخدام التطبيق.
‫AdsRequest: عنصر يحدّد طلب إعلانات. تحدّد طلبات الإعلانات عنوان URL لعلامة إعلانات نموذج عرض إعلانات الفيديو (VAST)، بالإضافة إلى مَعلمات إضافية، مثل سمات الإعلان.
AdsManager: عنصر يحتوي على الاستجابة لطلب الإعلانات، ويتحكّم في تشغيل الإعلانات، ويستمع إلى أحداث الإعلانات التي تنشئها حزمة SDK.

ملاحظة: بما أنّ إضافة IMA في ExoPlayer تُغلِّف حزمة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية في هذا الدليل، يتم استخدام كلّ من AdsRequest وAdsManager، ولكن لا يتم استدعاؤهما صراحةً.

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

قبل البدء، يجب تثبيت الإصدار 3.0 من Android Studio أو إصدار أحدث.

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

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

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

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

أولاً، في ملف build.gradle على مستوى التطبيق، أضِف عمليات استيراد للإضافات إلى قسم "التبعيات". بسبب حجم إضافة ExoPlayer IMA، عليك تنفيذ وتفعيل حزمة multidex هنا. هذا الإجراء ضروري للتطبيقات التي تم ضبط minSdkVersion فيها على 20 أو أقل. أضِف أيضًا compileOptions جديدًا لتحديد معلومات التوافق مع إصدار Java.

app/build.gradle

android {
    namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdkVersion 34

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
  }

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
      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.3.1'
    implementation 'androidx.media3:media3-exoplayer:1.3.1'
    implementation 'androidx.media3:media3-exoplayer-ima:1.3.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>

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

إذا كان تطبيقك يستهدف الإصدار 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>

3- أنشئ حاوية واجهة مستخدم الإعلان.

أنشئ العرض لاستخدامه كعرض PlayerView في ExoPlayer من خلال إنشاء عنصر StyledPlayerView باستخدام معرّف مناسب. غيِّر أيضًا الرمز androidx.constraintlayout.widget.ConstraintLayout إلى LinearLayout.

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

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.media3.ui.PlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

</LinearLayout>

4. أضِف عنوان URL للمحتوى وعنوان URL لعلامة الإعلان لطلب الإعلانات.

أضِف إدخالات إلى strings.xml لتخزين عنوان URL للمحتوى وعنوان URL لعلامة إعلان VAST.

app/src/main/res/values/strings.xml

<resources>
    <string name="app_name">Your_Project_Name</string>
    <string name="content_url"><![CDATA[https://storage.googleapis.com/gvabox/media/samples/stock.mp4]]></string>
    <string name="ad_tag_url"><![CDATA[https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=]]></string>

</resources>

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

أضِف عبارات الاستيراد لإضافات ExoPlayer. بعد ذلك، عدِّل فئة MainActivity لتوسيع Activity من خلال إضافة متغيّرات خاصة لPlayerView وSimpleExoPlayer وImaAdsLoader.

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


import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
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.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

public class MainActivity extends Activity {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

}

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

استبدِل طريقة onCreate وأضِف عمليات ضبط المتغيّرات المطلوبة لإنشاء عنصر adsLoader جديد باستخدام عنوان URL لعلامة الإعلان.

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

...

public class MainActivity extends Activity {

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    MultiDex.install(this);

    playerView = findViewById(R.id.player_view);

    // Create an AdsLoader.
      adsLoader =
        new ImaAdsLoader.Builder(/* context= */ this)
            .setAdEventListener(buildAdEventListener())
            .build();
  }

  public AdEvent.AdEventListener buildAdEventListener() {

    AdEvent.AdEventListener imaAdEventListener = event -> {
      AdEvent.AdEventType eventType = event.getType();
      // Log IMA events for debugging.
      // The ExoPlayer IMA extension already handles IMA events and does not need anything
      // additional here to function.
    };

    return imaAdEventListener;
  }

}

7- بدء تشغيل المشغّل وإيقافه

أضِف طرقًا لبدء تشغيل المشغّل وإيقافه. في الأسلوب initialize ، أنشئ SimpleExoPlayer. بعد ذلك، أنشئ AdsMediaSource واضبطه على المشغّل.

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

public class MainActivity extends Activity {

  ...

  private void releasePlayer() {
    adsLoader.setPlayer(null);
    playerView.setPlayer(null);
    player.release();
    player = null;
  }

  private void initializePlayer() {
    // Set up the factory for media sources, passing the ads loader and ad view providers.
    DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

    MediaSource.Factory mediaSourceFactory =
        new DefaultMediaSourceFactory(dataSourceFactory)
            .setLocalAdInsertionComponents(unusedAdTagUri -> adsLoader, playerView);

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

    // Create the MediaItem to play, specifying the content URI and ad tag URI.
    Uri contentUri = Uri.parse(getString(R.string.content_url));
    Uri adTagUri = Uri.parse(getString(R.string.ad_tag_url));
    MediaItem mediaItem =
        new MediaItem.Builder()
            .setUri(contentUri)
            .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
            .build();

    // Prepare the content and ad to be played with the SimpleExoPlayer.
    player.setMediaItem(mediaItem);
    player.prepare();

    // Set PlayWhenReady. If true, content and ads will autoplay.
    player.setPlayWhenReady(false);
  }
}

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

أخيرًا، أنشئ وظائف استدعاء لأحداث دورة حياة اللاعب:

onStart
onResume
onStop
onPause
onDestroy

ملاحظة: يستخدم مثال الرمز البرمجي القيمة onStart/onStop لحزمة SDK لنظام Android الإصدار 24 والإصدارات الأحدث، والقيمة onResume/onPause للإصدارات الأقدم من 24.

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

public class MainActivity extends Activity {

  private PlayerView playerView;
  private SimpleExoPlayer player;
  private ImaAdsLoader adsLoader;

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

      playerView = findViewById(R.id.player_view);

      // Create an AdsLoader.
      adsLoader =
        new ImaAdsLoader.Builder(/* context= */ this)
            .setAdEventListener(buildAdEventListener())
            .build();
  }

  @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
  protected void onDestroy() {
    super.onDestroy();
    adsLoader.release();
  }

  ...

}

هذا كل شيء! يمكنك الآن طلب الإعلانات وعرضها باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية. للتعرّف على ميزات إضافية لحزمة تطوير البرامج (SDK)، اطّلِع على الأدلة الأخرى أو عيّنات على GitHub.

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

نظرة عامة على IMA من جهة العميل

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

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

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

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

3- أنشئ حاوية واجهة مستخدم الإعلان.

4. أضِف عنوان URL للمحتوى وعنوان URL لعلامة الإعلان لطلب الإعلانات.

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

6- إنشاء مثيل adsLoader

7- بدء تشغيل المشغّل وإيقافه

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

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