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

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

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

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

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

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

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

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

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

پیش‌نیازها

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

ایجاد یک پروژه جدید اندروید استودیو

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

1. اندروید استودیو را شروع کنید.
2. شروع یک پروژه جدید اندروید استودیو را انتخاب کنید.
3. در صفحه «پروژه خود را انتخاب کنید» ، الگوی «بدون فعالیت» را انتخاب کنید.
4. روی بعدی کلیک کنید.
5. در صفحه پیکربندی پروژه ، نام پروژه خود را بنویسید و زبان جاوا را انتخاب کنید. توجه: کیت توسعه نرم‌افزار IMA DAI با کاتلین کار می‌کند، اما این راهنما از مثال‌های جاوا استفاده می‌کند.

• روی پایان کلیک کنید.

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

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

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

   dependencies {
       def media3_version = "1.8.0"
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
       implementation 'androidx.appcompat:appcompat:1.7.1'
       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 را تنظیم کنید

برای تنظیم رابط کاربری ExoPlayer، موارد زیر را انجام دهید:

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

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 مراجعه کنید. برای تنظیم استریم‌های خود، به بخش مدیریت تبلیغات در DAI مراجعه کنید.

این مرحله یک پخش زنده را تنظیم می‌کند. افزونه ExoPlayer IMA همچنین از پخش‌های DAI VOD پشتیبانی می‌کند. برای اطلاع از اینکه برنامه شما برای پخش‌های 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.common.util.Util;
   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

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

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

   /** 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 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)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

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

• مدیر تبلیغات گوگل (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

مدیریت رویدادهای بازیکن

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

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

• onStart()
• onStop()

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

• onResume()
• onPause()

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

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

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

@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
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 (اختیاری)

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

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

2. با استفاده از متد ImaServerSideAdInsertionUriBuilder() ، یک SSAI VOD URI ایجاد کنید:

   /**
    * 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)
         .setAdTagParameters(adTagParams)
         .build();
   }
   MyActivity.java
   

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

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