البدء باستخدام إضافة Exoplayer IMA

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

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

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

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

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

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

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

1- إنشاء مشروع جديد في Android Studio

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

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

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

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

app/build.gradle 
android {
    compileSdkVersion 30

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
  }

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 16
      targetSdkVersion 30
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.appcompat:appcompat:1.3.1'
    implementation 'com.google.android.exoplayer:exoplayer-core:2.19.0'
    implementation 'com.google.android.exoplayer:exoplayer-ui:2.19.0'
    implementation 'com.google.android.exoplayer:extension-ima:2.19.0'

    ...
}

أضِف أذونات المستخدمين التي تطلبها حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لطلب الإعلانات.

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>

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

    <com.google.android.exoplayer2.ui.StyledPlayerView
        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.multidex.MultiDex;
import com.google.android.exoplayer2.ExoPlayer;
import com.google.android.exoplayer2.MediaItem;
import com.google.android.exoplayer2.ext.ima.ImaAdsLoader;
import com.google.android.exoplayer2.source.DefaultMediaSourceFactory;
import com.google.android.exoplayer2.source.MediaSourceFactory;
import com.google.android.exoplayer2.ui.StyledPlayerView;
import com.google.android.exoplayer2.upstream.DataSource;
import com.google.android.exoplayer2.upstream.DefaultDataSourceFactory;
import com.google.android.exoplayer2.util.Util;

...

public class MainActivity extends Activity {

  private StyledPlayerView 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 StyledPlayerView 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).build();
  }

}

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

    MediaSourceFactory mediaSourceFactory =
        new DefaultMediaSourceFactory(dataSourceFactory)
                .setAdsLoaderProvider(unusedAdTagUri -> adsLoader)
                .setAdViewProvider(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 with the ad tag url.
      adsLoader = new ImaAdsLoader(this, Uri.parse(getString(R.string.ad_tag_url)));
  }

  @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.