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

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

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

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

نمای کلی سمت مشتری IMA

پیاده سازی سمت مشتری IMA شامل چهار جزء اصلی SDK است که در این راهنما نشان داده شده است:

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

توجه: از آنجایی که افزونه ExoPlayer IMA، IMA SDK را در این راهنما می‌پیچد، هر دو AdsRequest و AdsManager استفاده می‌شوند، اما به صراحت فراخوانی نمی‌شوند.

پیش نیازها

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

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

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

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

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

ابتدا در فایل build.gradle در سطح برنامه، import برای پسوند را به بخش وابستگی ها اضافه کنید. به دلیل اندازه پسوند ExoPlayer IMA، multidex را در اینجا پیاده سازی و فعال کنید. این برای برنامه هایی با minSdkVersion تنظیم شده روی 20 یا کمتر ضروری است. همچنین، برای تعیین اطلاعات سازگاری نسخه جاوا، compileOptions جدید اضافه کنید.

app/build.gradle

android {
    namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample'
    compileSdkVersion 34

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
  }

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample"
      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.3.1'
    implementation 'androidx.media3:media3-exoplayer:1.3.1'
    implementation 'androidx.media3:media3-exoplayer-ima:1.3.1'

    ...
}

مجوزهای کاربر مورد نیاز IMA 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 SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

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

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

توجه: نسخه‌های آینده کیت توسعه نرم‌افزار IMA به‌طور خودکار شامل این اعلان‌ها می‌شوند و با فایل مانیفست برنامه شما ادغام می‌شوند.

  <?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>

3. ظرف رابط کاربری تبلیغات را ایجاد کنید

با ایجاد یک شیء StyledPlayerView با شناسه مناسب، نمای مورد نظر را برای استفاده به عنوان ExoPlayer PlayerView ایجاد کنید. 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">

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

</LinearLayout>

4. URL محتوای خود و نشانی اینترنتی برچسب آگهی را برای درخواست تبلیغات اضافه کنید

ورودی‌هایی را به strings.xml اضافه کنید تا 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 IMA را وارد کنید

دستورهای import را برای پسوند 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.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.ImaAdsLoader;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.source.MediaSource;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

public class MainActivity extends Activity {

  private PlayerView 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 PlayerView 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)
            .setAdEventListener(buildAdEventListener())
            .build();
  }

  public AdEvent.AdEventListener buildAdEventListener() {

    AdEvent.AdEventListener imaAdEventListener = event -> {
      AdEvent.AdEventType eventType = event.getType();
      // Log IMA events for debugging.
      // The ExoPlayer IMA extension already handles IMA events and does not need anything
      // additional here to function.
    };

    return imaAdEventListener;
  }

}

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

    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(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

توجه: کد مثال از onStart/onStop برای Android SDK نسخه‌های 24 و بالاتر و onResume/onPause برای نسخه‌های قبل از 24 استفاده می‌کند.

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.
      adsLoader =
        new ImaAdsLoader.Builder(/* context= */ this)
            .setAdEventListener(buildAdEventListener())
            .build();
  }

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

  ...

}

همین! اکنون در حال درخواست و نمایش تبلیغات با IMA SDK هستید. برای آشنایی با ویژگی‌های اضافی SDK، به سایر راهنماها یا نمونه‌های موجود در GitHub مراجعه کنید.