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

Stay organized with collections Save and categorize content based on your preferences.

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

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

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

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

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

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

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

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

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

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

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

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

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.18.1'
    implementation 'com.google.android.exoplayer:exoplayer-ui:2.18.1'
    implementation 'com.google.android.exoplayer:extension-ima:2.18.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>

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 لإعلانات الوسائط التفاعلية

أضِف عبارات الاستيراد لإضافة 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) لإعلانات الوسائط التفاعلية (IMA). للتعرّف على الميزات الإضافية لحزمة تطوير البرامج (SDK)، يمكنك الاطّلاع على الأدلة الأخرى أو العيّنات على GitHub.