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

ExoPlayer پخش‌کننده رسانه Android است. این راهنما به شما نشان می‌دهد که چگونه از افزونه ExoPlayer IMA استفاده کنید. این افزونه از IMA DAI SDK برای درخواست و پخش جریانات رسانه‌ای با هر دو آگهی و محتوا استفاده می‌کند.

در زیر مزایای این افزونه فهرست شده است:

• کد موردنیاز برای ادغام ویژگی‌های IMA را ساده می‌کند.
• زمان لازم برای به‌روزرسانی به نسخه‌های جدید IMA را کاهش می‌دهد.

افزونه ExoPlayer IMA از پروتکل‌های جاری‌سازی HLS و DASH پشتیبانی می‌کند. در اینجا خلاصه‌ای آمده است:

پشتیبانی از جاری‌سازی افزونه ExoPlayer-IMA
	جاری‌سازی زنده	جاری‌سازی‌های ویدیو به‌درخواست
HLS
DASH

ExoPlayer-IMA نسخه ۱.۱.۰ و بالاتر از جاری‌سازی‌های زنده DASH پشتیبانی می‌کند.

این راهنما از راهنمای ExoPlayer استفاده می‌کند تا به شما کمک کند برنامه کاملی ایجاد کنید و افزونه را ادغام کنید. برای مشاهده نمونه کامل برنامه، ExoPlayerExample را در GitHub ببینید.

نکته کلیدی: افزونه ExoPlayer IMA به ExoPlayer نیاز دارد. اگر پخش‌کننده دیگری را ترجیح می‌دهید، راهنمای شروع به کار را دنبال کنید تا کیت توسعه نرم‌افزار IMA DAI را در برنامه‌تان ادغام کنید.

پیش‌نیازها

• استودیو Android
• AndroidX Media3 ExoPlayer نسخه ۱.۰.۰ یا جدیدتر برای پشتیبانی از DAI.

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

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

1. «استودیو Android» را راه‌اندازی کنید.
2. Start a new Android Studio project (شروع پروژه جدید Android Studio) را انتخاب کنید.
3. در صفحه انتخاب پروژه، الگوی بدون فعالیت را انتخاب کنید.
4. روی بعدی کلیک کنید.
5. در صفحه پیکربندی پروژه، نامی برای پروژه انتخاب کنید و Java را به‌عنوان زبان انتخاب کنید. توجه: IMA DAI SDK با Kotlin کار می‌کند، اما این راهنما از نمونه‌های Java استفاده می‌کند.

• روی تمام کلیک کنید؛

افزونه ExoPlayer IMA را به پروژه‌تان اضافه کنید

برای افزودن افزونه ExoPlayer IMA، کارهای زیر را انجام دهید:

1. واردات زیر را در بخش dependencies فایل build.gradle برنامه‌تان اضافه کنید:

   dependencies {
       def media3_version = "1.11.0"
       coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.21"))
       implementation("androidx.appcompat:appcompat:1.8.0")
       implementation("androidx.media3:media3-ui:$media3_version")
       implementation("androidx.media3:media3-exoplayer:$media3_version")
       implementation("androidx.media3:media3-exoplayer-hls:$media3_version")
       implementation("androidx.media3:media3-exoplayer-dash:$media3_version")
   
       // The library adds the IMA ExoPlayer integration for ads.
       implementation("androidx.media3:media3-exoplayer-ima:$media3_version")
   }
   build.gradle
   

2. اجازه‌های کاربری را که IMA DAI SDK برای درخواست آگهی نیاز دارد اضافه کنید:

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   AndroidManifest.xml
   

راه‌اندازی کردن ExoPlayer UI

برای راه‌اندازی ExoPlayer UI، کارهای زیر را انجام دهید:

1. شیء PlayerView را برای ExoPlayer ایجاد کنید.

2. نمای androidx.constraintlayout.widget.ConstraintLayout را به نمای LinearLayout تغییر دهید، همان‌طور که توسط افزونه ExoPlayer IMA توصیه شده است:

   <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:fitsSystemWindows="true"
           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>
   activity_my.xml
   

پارامترهای جاری‌سازی‌تان را اضافه کنید

برای دارایی‌های جاری‌سازی نمونه برای آزمایش پروژه‌تان، صفحه جاری‌سازی نمونه IMA را ببینید. برای راه‌اندازی جاری‌سازی‌های خودتان، بخش Ad Manager درباره درج آگهی پویا را ببینید.

این مرحله جاری‌سازی زنده را راه‌اندازی می‌کند. افزونه ExoPlayer IMA از جاری‌سازی‌های DAI VOD نیز پشتیبانی می‌کند. برای آشنایی با تغییراتی که برنامه‌تان برای جاری‌سازی‌های «ویدیو به‌درخواست» نیاز دارد، مرحله مربوط به جاری‌سازی‌های ویدیو به‌درخواست (VOD) را ببینید.

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

1. عبارت‌های وارد کردن زیر را برای افزونه ExoPlayer اضافه کنید:

   import static androidx.media3.common.C.CONTENT_TYPE_HLS;
   
   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.ImaServerSideAdInsertionMediaSource;
   import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder;
   import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
   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;
   import java.util.HashMap;
   import java.util.Map;
   MyActivity.java
   

2. در MyActivity.java، این متغیرهای خصوصی را اضافه کنید:

   • PlayerView
   • ExoPlayer
   • ImaServerSideAdInsertionMediaSource.AdsLoader
   • ImaServerSideAdInsertionMediaSource.AdsLoader.State

   برای آزمایش با جاری‌سازی HLS Big Buck Bunny (Live)، کلید دارایی آن را اضافه کنید. می‌توانید جاری‌سازی‌های بیشتری را برای آزمایش در صفحه جاری‌سازی نمونه IMA پیدا کنید.

3. یک ثابت KEY_ADS_LOADER_STATE برای ذخیره و بازیابی وضعیت AdsLoader ایجاد کنید:

   /** Main Activity. */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   public class MyActivity extends Activity {
   
     private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
     private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
     private static final String LOG_TAG = "ImaExoPlayerExample";
     private static final String NETWORK_CODE = "21775744923";
   
     private PlayerView playerView;
     private TextView logText;
     private ExoPlayer player;
     private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
     private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;
     private ImaSdkSettings imaSdkSettings;
   MyActivity.java
   

ایجاد نمونه adsLoader

روش onCreate را لغو کنید. در آن، PlayerView را پیدا کنید و ببینید آیا AdsLoader.State ذخیره‌شده‌ای وجود دارد یا نه. هنگام مقداردهی اولیه شیء 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);

  // Checks if there is a saved AdsLoader state to be used later when initiating the AdsLoader.
  if (savedInstanceState != null) {
    Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE);
    if (adsLoaderStateBundle != null) {
      adsLoaderState =
          ImaServerSideAdInsertionMediaSource.AdsLoader.State.fromBundle(adsLoaderStateBundle);
    }
  }
}

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

مهم: برای بهبود زمان بار کردن IMA، روش ImaSdkFactory.initialize() را در اولین فرصت ممکن در چرخه حیات برنامه فراخوانی کنید. فراخوانی زودهنگام این روش، زمان لازم برای بار کردن منابع ضروری توسط IMA را قبل‌از اولین درخواست جاری‌سازی به حداکثر می‌رساند. فراخوانی روش ImaSdkFactory.initialize() یک نمونه ImaSdkSettings را می‌پذیرد. مطمئن شوید که از همان مقادیر تنظیمات در اینجا و هنگام ایجاد نمونه AdsLoader استفاده می‌کنید. این نمونه از روش کمکی getImaSdkSettings() استفاده می‌کند تا مطمئن شود مقادیر تنظیمات یکسان هستند. برای اطلاعات بیشتر، راهنمای بهینه‌سازی زمان بار کردن IMA> را ببینید.

افزودن روش‌هایی برای مقداردهی اولیه پخش‌کننده

روشی برای راه‌اندازی پخش‌کننده اضافه کنید. این روش باید کارهای زیر را انجام دهد:

• نمونه AdsLoader ایجاد کنید.
• ExoPlayer را ایجاد کنید.
• بااستفاده از کلید دارایی جاری‌سازی زنده، یک MediaItem ایجاد کنید.
• MediaItem را برای پخش‌کننده خود تنظیم کنید.

// Create a server side ad insertion (SSAI) AdsLoader.
private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
      new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

  // Attempts to set the AdsLoader state if available from a previous session.
  if (adsLoaderState != null) {
    adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
  }

  return adsLoaderBuilder
      .setAdEventListener(buildAdEventListener())
      .setImaSdkSettings(getImaSdkSettings())
      .build();
}

private void initializePlayer() {
  adsLoader = createAdsLoader();

  // Set up the factory for media sources, passing the ads loader.
  DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);

  DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory);

  // MediaSource.Factory to create the ad sources for the current player.
  ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
      new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory);

  // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory.
  // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server
  // side inserted ad streams.
  mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);

  // Create a SimpleExoPlayer 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 stream URI.
  Uri ssaiUri = buildLiveStreamUri(SAMPLE_ASSET_KEY, CONTENT_TYPE_HLS);
  MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiUri);

  // Prepare the content and ad to be played with the ExoPlayer.
  player.setMediaItem(ssaiMediaItem);
  player.prepare();

  // Set PlayWhenReady. If true, content and ads will autoplay.
  player.setPlayWhenReady(false);
}

/**
 * Builds an IMA SSAI live stream URI for the given asset key and format.
 *
 * @param assetKey The asset key of the live stream.
 * @param format The format of the live stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the live stream.
 */
public Uri buildLiveStreamUri(String assetKey, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setAssetKey(assetKey)
      .setFormat(format)
      .setNetworkCode(NETWORK_CODE)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

توجه: این بخش از روش‌هایی با نام‌هایی استفاده می‌کند که به مفاهیم درج آگهی سمت سرور (SSAI) اشاره دارند.

• Google Ad Manager DAI نمونه‌ای از SSAI است.
• افزونه ExoPlayer IMA این راهنما به‌طور خاص با Ad Manager DAI کار می‌کند. افزونه ExoPlayer IMA از راه‌حل‌های مختلف SSAI نیز پشتیبانی می‌کند.

افزودن روشی برای رها کردن بازیکن

روشی برای رها کردن بازیکن اضافه کنید. این روش باید کنش‌های زیر را به‌ترتیب انجام دهد:

• ارجاع‌های پخش‌کننده را روی null تنظیم کنید و منابع پخش‌کننده را آزاد کنید.
• وضعیت adsLoader را منتشر کنید.

private void releasePlayer() {
  // Set the player references to null and release the player's resources.
  playerView.setPlayer(null);
  player.release();
  player = null;

  // Release the adsLoader state so that it can be initiated again.
  adsLoaderState = adsLoader.release();
}
MyActivity.java

رسیدگی به رویدادهای بازیکن

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

برای Android API سطح ۲۴ و بالاتر، از روش‌های زیر استفاده کنید:

• onStart()
• onStop()

برای سطوح میانای برنامه‌سازی کاربردی Android قدیمی‌تر از ۲۴، از روش‌های زیر استفاده کنید:

• onResume()
• onPause()

روش‌های onStart() و onResume() به playerView.onResume() نگاشت می‌شوند، درحالی‌که onStop() و onPause() به playerView.onPause() نگاشت می‌شوند.

نکته کلیدی: این مثال از کیت توسعه نرم‌افزار Android نسخه ۲۴+ و نسخه‌های قدیمی‌تر پشتیبانی می‌کند. از onStart()/onStop() برای کیت توسعه نرم‌افزار Android نسخه ۲۴ و بالاتر، و از onResume()/onPause() برای نسخه‌های قدیمی‌تر از ۲۴ استفاده کنید.

این مرحله همچنین از رویداد onSaveInstanceState() برای ذخیره کردن adsLoaderState استفاده می‌کند.

@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
public void onSaveInstanceState(Bundle outState) {
  // Attempts to save the AdsLoader state to handle app backgrounding.
  if (adsLoaderState != null) {
    outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle());
  }
}
MyActivity.java

راه‌اندازی جاری‌سازی ویدیو به‌درخواست (اختیاری)

اگر برنامه‌تان باید محتوای VOD را با آگهی پخش کند، این مراحل را دنبال کنید:

1. CMS ID و Video ID را برای جاری‌سازی «ویدیو به‌درخواست» اضافه کنید. برای آزمایش، از این پارامترهای جاری‌سازی استفاده کنید:
   • شناسه CMS: "2548831"
   • شناسه ویدیو: "tears-of-steel"

2. بااستفاده از روش ImaServerSideAdInsertionUriBuilder()، یک شناسه منبع یکسان برای ویدیو به‌درخواست با درج آگهی سمت سرور ایجاد کنید:

   /**
    * Builds an IMA SSAI VOD stream URI for the given CMS ID, video ID, and format.
    *
    * @param cmsId The CMS ID of the VOD stream.
    * @param videoId The video ID of the VOD stream.
    * @param format The format of the VOD stream request, either {@code CONTENT_TYPE_HLS} or {@code
    *     CONTENT_TYPE_DASH}.
    * @return The URI of the VOD stream.
    */
   public Uri buildVodStreamUri(String cmsId, String videoId, int format) {
     Map<String, String> adTagParams = new HashMap<String, String>();
     // Update the adTagParams map with any parameters.
     // For more information, see https://support.google.com/admanager/answer/7320899
   
     return new ImaServerSideAdInsertionUriBuilder()
         .setContentSourceId(cmsId)
         .setVideoId(videoId)
         .setFormat(format)
         .setNetworkCode(NETWORK_CODE)
         .setAdTagParameters(adTagParams)
         .build();
   }
   MyActivity.java
   

3. بااستفاده از روش MediaItem.fromUri()، شناسه منبع یکسان جاری‌سازی جدید ویدیو به‌درخواست را به‌عنوان فایل رسانه‌ای پخش‌کننده تنظیم کنید.

اگر موفقیت‌آمیز بود، می‌توانید با ExoPlayer IMA افزونه، جاری‌سازی رسانه را درخواست و پخش کنید. برای مشاهده نمونه کامل، به نمونه‌های Android DAI در GitHub مراجعه کنید.