این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

در اینجا برخی از مزایای افزونه آورده شده است:

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

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

پشتیبانی از جریان برنامه افزودنی ExoPlayer-IMA
	پخش زنده	جریان های VOD
HLS
داش

پخش‌های زنده DASH در ExoPlayer-IMA نسخه 1.1.0+ پشتیبانی می‌شوند.

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

پیش نیازها

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

یک پروژه Android Studio جدید ایجاد کنید

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

Android Studio را راه اندازی کنید.
شروع پروژه جدید Android Studio را انتخاب کنید.
در صفحه Choose your project ، الگوی No Activity را انتخاب کنید.
روی Next کلیک کنید.
در صفحه Configure your project ، نام پروژه خود را گذاشته و جاوا را برای زبان انتخاب کنید.
توجه: IMA DAI SDK با Kotlin سازگار است. با این حال، مثال ارائه شده در این راهنما از جاوا استفاده می کند.
روی Finish کلیک کنید.

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

در بخش dependencies ، واردات برای پسوند را به فایل build.gradle در سطح برنامه اضافه کنید.

برنامه خود را روی multidex پیکربندی و فعال کنید. این به دلیل اندازه برنامه افزودنی ضروری است و برای برنامه‌هایی با minSdkVersion تنظیم شده روی Android 4.4W (سطح API 20) یا پایین‌تر لازم است.

در اینجا یک مثال است:

app/build.gradle

android {

  ...

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

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.1.1'
    implementation 'androidx.media3:media3-exoplayer:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-hls:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-dash:1.1.1'

    // Adding the ExoPlayer IMA extension for ads will also include the IMA
    // SDK as a dependency.
    implementation 'androidx.media3:media3-exoplayer-ima:1.1.1'
}

مجوزهای کاربر مورد نیاز IMA DAI SDK را برای درخواست تبلیغات اضافه کنید:

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 DAI SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

اعلامیه های قصد را اضافه کنید

اگر برنامه شما Android 11 (سطح API 30) یا بالاتر را هدف قرار می‌دهد، نسخه‌های فعلی و اخیر IMA DAI SDK به یک اعلامیه صریح از قصد برای باز کردن پیوندهای وب نیاز دارند. قطعه زیر را به فایل مانیفست برنامه خود اضافه کنید تا امکان کلیک روی تبلیغات فعال شود (کاربران روی دکمه بیشتر بدانید ).

  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.example.project name">

      ...

    </application>

    <queries>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="https" />
      </intent>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="http" />
      </intent>
    </queries>
  </manifest>

رابط کاربری ExoPlayer را تنظیم کنید

شی PlayerView را برای استفاده توسط ExoPlayer ایجاد کنید.

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

در اینجا یک مثال است:

app/src/main/res/layout/activity_my.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:background="@android:color/black"
    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="match_parent" />

</LinearLayout>

پارامترهای جریان خود را اضافه کنید

برای آزمایش پروژه خود، صفحه جریان نمونه IMA را برای نمونه دارایی های جریان ببینید. همچنین برای اطلاعات در مورد تنظیم جریان های خود به بخش Ad Manager در DAI مراجعه کنید.

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

پسوند ExoPlayer IMA را وارد کنید

دستورهای import را برای پسوند ExoPlayer اضافه کنید.

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

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

برای ذخیره و بازیابی حالت AdsLoader یک ثابت KEY_ADS_LOADER_STATE ایجاد کنید.

در اینجا یک مثال است:

app/src/main/java/com/example/ `project name` /MyActivity.java


import static androidx.media3.common.C.CONTENT_TYPE_HLS;

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.annotation.OptIn;
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.exoplayer.util.EventLogger;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

}

یک نمونه `adsLoader` ایجاد کنید

روش onCreate را بازنویسی کنید تا PlayerView را پیدا کنید و یک AdsLoader.State ذخیره شده را بررسی کنید، که می تواند هنگام شروع شی adsLoader استفاده شود.

همچنین، در صورت نیاز به تعداد متد برنامه و minSdkVersion multidex را فعال کنید (همانطور که در مرحله 2 توضیح داده شد).

در اینجا یک مثال است:

app/src/main/java/com/example/ `project name` /MyActivity.java

...

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 PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

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

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

}

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

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

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

در اینجا یک مثال است:

app/src/main/java/com/example/ `project name` /MyActivity.java

public class MyActivity extends Activity {

  ...

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

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

    return adsLoaderBuilder.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 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);

    // Build an IMA SSAI media item to prepare the player with.
    Uri ssaiLiveUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setAssetKey(SAMPLE_ASSET_KEY)
            .setFormat(CONTENT_TYPE_HLS) // Use CONTENT_TYPE_DASH for dash streams.
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiLiveUri);

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

روشی برای آزاد کردن پخش کننده اضافه کنید

یک روش برای آزاد کردن پخش کننده در این دنباله اضافه کنید:

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

app/src/main/java/com/example/ `project name` /MyActivity.java

public class MyActivity extends Activity {

  ...

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

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

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

برای پشتیبانی از Android SDK نسخه 24+:

برای پشتیبانی از نسخه‌های Android SDK کمتر از ۲۴: - onResume() - onPause()

onStart() و onResume() به playerView.onResume() و onStop() و onPause() به playerView.onPause() نگاشت.

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

app/src/main/java/com/example/ `project name` /MyActivity.java

public class MyActivity extends Activity {

  ...

  @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());
    }
  }

  ...

}

تنظیم جریان VOD (اختیاری)

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

یک CMS ID و Video ID برای جریان آزمایش VOD اضافه کنید.
یک URI SSAI VOD با استفاده از ImaServerSideAdInsertionUriBuilder() ایجاد کنید.
از این URI جدید به عنوان آیتم رسانه پخش کننده خود استفاده کنید.

app/src/main/java/com/example/ `project name` /MyActivity.java

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 SAMPLE_CMS_ID = "2548831";
  private static final String SAMPLE_VIDEO_ID = "tears-of-steel";

  ...

  private void initializePlayer() {

     ...

    Uri ssaiVodUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setContentSourceId(SAMPLE_CMS_ID)
            .setVideoId(SAMPLE_VIDEO_ID)
            .setFormat(CONTENT_TYPE_HLS)
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiVodUri);

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

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

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

پیش نیازها

یک پروژه Android Studio جدید ایجاد کنید

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

app/build.gradle

app/src/main/AndroidManifest.xml

اعلامیه های قصد را اضافه کنید

رابط کاربری ExoPlayer را تنظیم کنید

app/src/main/res/layout/activity_my.xml

پارامترهای جریان خود را اضافه کنید

پسوند ExoPlayer IMA را وارد کنید

app/src/main/java/com/example/ project name /MyActivity.java

یک نمونه adsLoader ایجاد کنید

app/src/main/java/com/example/ project name /MyActivity.java

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

app/src/main/java/com/example/ project name /MyActivity.java

روشی برای آزاد کردن پخش کننده اضافه کنید

app/src/main/java/com/example/ project name /MyActivity.java

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

app/src/main/java/com/example/ project name /MyActivity.java

تنظیم جریان VOD (اختیاری)

app/src/main/java/com/example/ project name /MyActivity.java

app/src/main/java/com/example/ `project name` /MyActivity.java

یک نمونه `adsLoader` ایجاد کنید

app/src/main/java/com/example/ `project name` /MyActivity.java

app/src/main/java/com/example/ `project name` /MyActivity.java

app/src/main/java/com/example/ `project name` /MyActivity.java

app/src/main/java/com/example/ `project name` /MyActivity.java

app/src/main/java/com/example/ `project name` /MyActivity.java