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

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

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

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

نظرة عامة على إعلانات الوسائط التفاعلية من جهة العميل

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

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

ملاحظة: نظرًا لأن إضافة إعلانات الوسائط التفاعلية في ExoPlayer تشمل حزمة تطوير البرامج لإعلانات الوسائط التفاعلية في هذا الدليل، يتم استخدام كل من AdsRequest وAdsManager، ولكن لا يتم استخدامهما بشكل صريح.

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

قبل أن تبدأ، تحتاج إلى الإصدار 3.0 من "استوديو Android" أو الإصدارات الأحدث

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

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

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

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

أولاً، في الملف build.gradle على مستوى التطبيق، أضِف عمليات استيراد للإضافة إلى قسم التبعيات. نظرًا لحجم إضافة ExoPlayer لإعلانات الوسائط التفاعلية، يجب تنفيذها وتفعيلها هنا. وهذا الإجراء ضروري للتطبيقات التي تم ضبط 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>

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

إذا كان تطبيقك يستهدف Android 11 (المستوى 30 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، لا يمكن تغيير تتطلب حزمة تطوير البرامج لإعلانات الوسائط التفاعلية إعلان صريح عن نية فتح روابط الويب. أضف المقتطف التالي إلى ملف البيان لتطبيقك لتفعيل نسب النقر إلى الظهور للإعلانات (ينقر المستخدمون على مزيد من المعلومات ).

  <?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- إنشاء حاوية واجهة مستخدم الإعلان

إنشاء طريقة العرض لاستخدامها كـ ExoPlayer PlayerView من خلال إنشاء 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

أضف عبارات الاستيراد للإضافة 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. تهيئة المشغّل وتحريره

إضافة طرق لإعداد المشغّل وتحريره في الإعداد هي إنشاء 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

نظرة عامة على إعلانات الوسائط التفاعلية من جهة العميل

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

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

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

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

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

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

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

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

7. تهيئة المشغّل وتحريره

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

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