شروع به کار با افزونه Exoplayer IMA

کیت‌های توسعه نرم‌افزار IMA ادغام آگهی‌های چندرسانه‌ای در وب‌سایت‌ها و برنامه‌هایتان را آسان می‌کنند. کیت‌های توسعه نرم‌افزار IMA می‌توانند از هر سرور آگهی سازگار با VAST درخواست آگهی کنند و بازپخش آگهی را در برنامه‌هایتان مدیریت کنند. با کیت‌های توسعه نرم‌افزار سمت کارخواه IMA، کنترل بازپخش ویدیو محتوا را حفظ می‌کنید، درحالی‌که کیت توسعه نرم‌افزار بازپخش آگهی را مدیریت می‌کند. آگهی‌ها در پخش‌کننده ویدیو جداگانه‌ای که روی پخش‌کننده ویدیو محتوای برنامه قرار دارد پخش می‌شوند.

این راهنما نحوه ادغام کردن «کیت توسعه نرم‌افزار IMA» را در پروژه خالی «استودیو Android» بااستفاده از افزونه ExoPlayer IMA نشان می‌دهد. اگر می‌خواهید یک نمونه ادغام کامل‌شده را مشاهده یا دنبال کنید، BasicExample را از GitHub بارگیری کنید.

نمای کلی سمت کارخواه IMA

پیاده‌سازی سمت کارخواه IMA شامل چهار عنصر اصلی کیت توسعه نرم‌افزار است که در این راهنما نشان داده شده است:

  • AdDisplayContainer: شیء دربرگیرنده‌ای که مشخص می‌کند IMA عناصر میانای کاربر آگهی را کجا ارائه دهد و قابلیت مشاهده را اندازه‌گیری کند، ازجمله Active View و Open Measurement.
  • AdsLoader: شیئی که آگهی‌ها را درخواست می‌کند و رویدادهای پاسخ‌های درخواست آگهی را مدیریت می‌کند. فقط باید یک بار بارکننده آگهی‌ها را نمونه‌سازی کنید که می‌تواند درطول عمر برنامه دوباره استفاده شود.
  • AdsRequest: شیئی که درخواست آگهی را تعریف می‌کند. درخواست‌های آگهی نشانی وب برچسب آگهی VAST و همچنین پارامترهای اضافی، مانند ابعاد آگهی را مشخص می‌کنند.
  • AdsManager: شیئی که حاوی پاسخ به درخواست آگهی است، پخش آگهی را کنترل می‌کند، و به رویدادهای آگهی که ازسوی کیت توسعه نرم‌افزار راه‌اندازی می‌شوند گوش می‌دهد.

پیش‌نیازها

قبل‌از شروع، به Android Studio 3.0 یا بالاتر نیاز دارید.

۱. ایجاد پروژه جدید «استودیو Android»

برای ایجاد پروژه Android Studio، مراحل زیر را تکمیل کنید:

  1. «استودیو Android» را راه‌اندازی کنید.
  2. شروع پروژه جدید Android Studio را انتخاب کنید.
  3. در صفحه انتخاب پروژه، الگوی فعالیت خالی را انتخاب کنید.
  4. روی بعدی کلیک کنید.
  5. در صفحه پیکربندی پروژه، نامی برای پروژه خود انتخاب کنید و زبان Java را انتخاب کنید.
  6. روی تمام کلیک کنید؛

۲. افزودن افزونه ExoPlayer IMA به پروژه

ابتدا، در فایل build.gradle سطح برنامه، واردات را برای افزونه به بخش وابستگی‌ها اضافه کنید. همچنین، compileOptions جدیدی اضافه کنید تا اطلاعات سازگاری نسخه Java را مشخص کنید.

apply plugin: 'com.android.application'

android {
    namespace = 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdk = 36

    compileOptions {
        // Required by IMA SDK v3.37.0+
        coreLibraryDesugaringEnabled = true

        // Java 17 required by Gradle 8+
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    defaultConfig {
        applicationId = "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
        minSdkVersion(24)
        targetSdkVersion(36)
        versionCode = 1
        versionName = "1.0"
    }
    buildTypes {
        release {
            minifyEnabled = true
            proguardFiles(getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro')
        }
    }
}

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.11.0"
    coreLibraryDesugaring('com.android.tools:desugar_jdk_libs:2.1.5')
    implementation("androidx.media3:media3-ui:$media3_version")
    implementation("androidx.media3:media3-exoplayer:$media3_version")

    // The library adds the IMA ExoPlayer integration for ads.
    implementation("androidx.media3:media3-exoplayer-ima:$media3_version")
}

۳. ساختن محتوی واسط کاربر آگهی

با ایجاد یک androidx.media3.ui.PlayerView، نما را برای استفاده به‌عنوان ExoPlayer PlayerView ایجاد کنید. همچنین، androidx.constraintlayout.widget.ConstraintLayout را به LinearLayout تغییر دهید.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".MyActivity"
    tools:ignore="MergeRootFrame">

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

    <!-- UI element for viewing SDK event log -->
    <TextView
        android:id="@+id/logText"
        android:gravity="bottom"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:maxLines="100"
        android:scrollbars="vertical"
        android:textSize="@dimen/font_size">
    </TextView>

</LinearLayout>

۴. افزونه ExoPlayer IMA را وارد کنید

بیانیه‌های وارد کردن را برای افزونه ExoPlayer اضافه کنید:

import android.annotation.SuppressLint;
import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import android.text.method.ScrollingMovementMethod;
import android.util.Log;
import android.widget.TextView;
import androidx.media3.common.MediaItem;
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 com.google.ads.interactivemedia.v3.api.AdEvent;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;

سپس، کلاس MainActivity را به‌روز کنید تا با افزودن متغیرهای خصوصی برای PlayerView، ExoPlayer، ImaAdsLoader، و ImaSdkSettings،‏ Activity را گسترش دهید:

/** Main Activity. */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class MyActivity extends Activity {

  private static final String SAMPLE_VIDEO_URL =
      "https://storage.googleapis.com/gvabox/media/samples/stock.mp4";
  private static final String SAMPLE_VAST_TAG_URL =
      "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&correlator=";
  private static final String LOG_TAG = "ImaExoPlayerExample";

  private PlayerView playerView;
  private TextView logText;
  private ExoPlayer player;
  private ImaAdsLoader adsLoader;
  private ImaSdkSettings imaSdkSettings;

۵. ایجاد نمونه adsLoader

روش onCreate را رونویسی کنید و تخصیص‌های متغیر لازم را برای ایجاد شیء adsLoader جدید با نشانی وب برچسب آگهی اضافه کنید.

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

  // Initialize the IMA SDK as early as possible when the app starts. If your app already
  // overrides Application.onCreate(), call this method inside the onCreate() method.
  // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
  ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());

  playerView = findViewById(R.id.player_view);

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

روش buildAdEventListener() را برای برگرداندن شیء AdEventListener ایجاد کنید تا رویدادهای IMA را برای اشکال‌زدایی ثبت کند. افزونه ExoPlayer IMA ازقبل رویدادهای IMA را مدیریت می‌کند و برای عملکرد در اینجا به چیز اضافه‌ای نیاز ندارد.

public AdEvent.AdEventListener buildAdEventListener() {
  logText = findViewById(R.id.logText);
  logText.setMovementMethod(new ScrollingMovementMethod());

  return event -> {
    AdEvent.AdEventType eventType = event.getType();
    if (eventType == AdEvent.AdEventType.AD_PROGRESS) {
      return;
    }
    String log = "IMA event: " + eventType;
    if (logText != null) {
      logText.append(log + "\n");
    }
    Log.i(LOG_TAG, log);
  };
}

روش کمکی getImaSdkSettings() را برای برگرداندن شیء ImaSdkSettings به‌منظور تنظیم هریک از تنظیمات «کیت توسعه نرم‌افزار IMA» ایجاد کنید:

private ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    // Set any IMA SDK settings here.
  }
  return imaSdkSettings;
}

‫۶. مقداردهی اولیه و انتشار پخش‌کننده

روش‌هایی برای انتشار و مقداردهی اولیه پخش‌کننده اضافه کنید. در initializePlayer() روش، ExoPlayer را ایجاد کنید. سپس، AdsMediaSource را ایجاد کنید و آن را روی پخش‌کننده تنظیم کنید:

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(SAMPLE_VIDEO_URL);
  Uri adTagUri = Uri.parse(SAMPLE_VAST_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);
}

‫۷. مدیریت رویدادهای پخش‌کننده

درنهایت، برای رویدادهای چرخه حیات پخش‌کننده، فراخوانی‌های برگشتی ایجاد کنید:

  • onStart
  • onResume
  • onStop
  • onPause
  • onDestroy
@Override
public void onStart() {
  super.onStart();
  initializePlayer();
  if (playerView != null) {
    playerView.onResume();
  }
}

@Override
public void onResume() {
  super.onResume();
  if (player == null) {
    initializePlayer();
    if (playerView != null) {
      playerView.onResume();
    }
  }
}

@Override
public void onPause() {
  super.onPause();
}

@Override
public void onStop() {
  super.onStop();
  if (playerView != null) {
    playerView.onPause();
  }
  releasePlayer();
}

@Override
protected void onDestroy() {
  adsLoader.release();

  super.onDestroy();
}

اکنون با موفقیت درحال درخواست و نمایش آگهی‌ها با «کیت توسعه نرم‌افزار IMA» هستید. برای آشنایی با ویژگی‌های پیشرفته بیشتر، راهنماهای دیگر یا نمونه‌های GitHub را کاوش کنید.