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

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

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

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

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

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

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

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

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

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

  1. شغِّل Android Studio.
  2. اختَر بدء مشروع جديد على "استوديو Android".
  3. في صفحة اختيار مشروعك، اختَر النموذج فارغ النشاط.
  4. انقر على Next (التالي).
  5. في صفحة Configure your project (إعداد مشروعك)، أدخِل اسمًا لمشروعك واختَر Java للغة.
  6. انقر على إنهاء.

2- إدراج إضافة 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 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- تهيئة المشغّل وإفلاته

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