پخش آگهی صوتی پس زمینه

این راهنما برای ناشرانی در نظر گرفته شده است که علاقه مند به بارگیری تبلیغات صوتی در برنامه های اندرویدی خود هستند.

مهم: پخش تبلیغات ویدیویی در حالت پس‌زمینه را توصیه نمی‌کنیم.

پیش نیازها

• IMA Android SDK نسخه 3.16.1 یا بالاتر.

به ناشران توصیه می کنیم در صورتی که در حال حاضر برنامه پخش کننده صوتی ندارند، به مثال پخش کننده صوتی در github به عنوان نقطه شروع نگاه کنند. این مثال از ExoPlayer به عنوان پخش کننده پیش زمینه استفاده می کند. بقیه این راهنما ویژگی های لازم برای پخش صدای پس زمینه تبلیغات IMA را شرح می دهد.

نکته کلیدی: Basic Example پسوند Exoplayer-IMA را پیاده سازی می کند که اکثر تنظیمات IMA SDK را مدیریت می کند. به همین دلیل، مثال پایه نمی تواند به عنوان نقطه شروع برای این راهنما استفاده شود.

اضافه کردن پخش تبلیغات پس زمینه به برنامه شما

برای ادامه پخش موسیقی و تبلیغات صوتی زمانی که برنامه در حالت پس‌زمینه است، می‌توانید یک مؤلفه Service ایجاد کنید که حاوی یک پخش‌کننده صوتی سفارشی و یک بارکننده آگهی است.

اگر برنامه شما دارای MainActivity و AudioPlayerService برای پخش صدا است، می توانید فایل AndroidManifest.xml خود را مطابق شکل زیر تغییر دهید:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="…">
  <uses-permission android:name="android.permission.INTERNET"/>
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
  <application … >
    <activity android:name=".MainActivity" android:exported="true">
      <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
      </intent-filter>
    </activity>
    <service android:name=".AudioPlayerService"
             android:exported="false"/>
  </application>
</manifest>

در این سرویس، می‌توانید یک پخش‌کننده صوتی سفارشی ایجاد کنید، که می‌تواند هر پخش‌کننده رسانه‌ای باشد تا زمانی که رابط VideoAdPlayer را برای تعامل با IMA SDK نیز پیاده‌سازی کند.

IMA SDK نسخه 3.16.1 یک تابع جدید به createAudioAdDisplayContainer اضافه کرد تا یک محفظه تخصصی برای لودر آگهی برای درخواست تبلیغات صوتی ایجاد کند.

قطعه کد زیر نمونه ای از AudioPlayerService برای مقداردهی اولیه و ایجاد درخواست های تبلیغات صوتی را نشان می دهد.

import android.app.Service;

import com.google.ads.interactivemedia.v3.api.AdDisplayContainer;
import com.google.ads.interactivemedia.v3.api.AdsLoader;
import com.google.ads.interactivemedia.v3.api.AdsRequest;
import com.google.ads.interactivemedia.v3.api.CompanionAdSlot;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
import com.google.ads.interactivemedia.v3.api.player.VideoAdPlayer;

import com.google.common.collect.ImmutableList;

/** Plays music and ads even when the app enters background mode. */
public class AudioPlayerService extends Service {

  /**
   * A custom audio player that implements the `VideoAdPlayer` interface.
   */
  private VideoAdPlayer audioPlayer;

  /**
   * An object to create other SDK objects: `AdDisplayContainer`, `AdsLoader` and `AdRequest`.
   */
  private ImaSdkFactory sdkFactory;

  /**
   * An object to make ad requests that would return an `AdsManager`.
   */
  private AdsLoader adsLoader;

  /**
   * An optional list of ViewGroup for rendering companion banners.
   */
  private ImmutableList<CompanionAdSlot> companionAdSlots;

  /**
   * Creates an AdsLoader for requesting ads and handling ad events.
   */
  public void initializeAds() {
    sdkFactory = ImaSdkFactory.getInstance();
    ImaSdkSettings imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    AdDisplayContainer container = ImaSdkFactory.createAudioAdDisplayContainer(this, audioPlayer);
    if (companionAdSlots != null) {
      container.setCompanionSlots(companionAdSlots);
    }
    adsLoader = sdkFactory.createAdsLoader(this, imaSdkSettings, container);

    // Adds event handling logic for ads.
    // For more details, see
    // https://developers.google.com/interactive-media-ads/docs/sdks/android#create-an-adsloader
    adsLoader.addAdsLoadedListener(…);
    adsLoader.addAdErrorListener(…);
  }

  /**
   * Adds a companion ad slot. This slot is not required but can be set in ads initialization.
   *
   * @param companionAdSlot UI container for rendering companion banners.
   */
  public void addCompanionAdSlot(CompanionAdSlot companionAdSlot) {
    this.companionAdSlots = ImmutableList.of(companionAdSlot);
  }

  /**
   * Makes an audio ad request.
   *
   * @param adTagUrl Url to download an ad tag.
   */
  public void requestAd(String adTagUrl) {
    AdsRequest request = sdkFactory.createAdsRequest();
    request.setAdTagUrl(adTagUrl);
    adsLoader.requestAds(request);
  }
  ...
}

استفاده از تبلیغات با جایگاه های تبلیغاتی همراه

می توانید تبلیغات را با یا بدون اسلات تبلیغات همراه مقداردهی کنید. اگر می‌خواهید تبلیغات همراه را ارائه کنید، باید دسترسی AudioPlayerService به کلاس MainActivity را از طریق بایندر سرویس، مطابق شکل زیر فراهم کنید:

import android.app.Service;
import android.content.Intent;
import android.os.Binder;
import android.os.IBinder;

import androidx.annotation.Nullable;
...
/** Plays music and ads even when the app enters background mode. */
public class AudioPlayerService extends Service {
  ...
  @Nullable
  @Override
  public IBinder onBind(Intent intent) {
    return new ServiceBinder(this);
  }

  /**
   * Provides access to the `AudioPlayerService` instance after binding.
   */
  public class ServiceBinder extends Binder {
    private final AudioPlayerService boundService;

    /**
     * @param service The bound instance of the service
     */
    public ServiceBinder(AudioPlayerService service) {
      boundService = service;
    }

    public AudioPlayerService getBoundService() {
      return boundService;
    }
  }
}

می‌توانید تابع addCompanionAdSlot() را فراخوانی کنید و یک محفظه رابط کاربری را برای رندر کردن تبلیغات بنر همراه در حین تنظیم اولیه تبلیغات از کلاس MainActivity ارسال کنید.

import android.app.Activity;
import android.content.ComponentName;
import android.content.Context;
import android.content.ServiceConnection;
import android.os.Bundle;
import android.os.IBinder;
import android.view.ViewGroup;

import com.google.ads.interactivemedia.v3.api.CompanionAdSlot;
import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;

public class MainActivity extends Activity {

  private AudioPlayerService boundService;
  private ServiceConnection connection;

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

    ImaSdkFactory sdkFactory = ImaSdkFactory.getInstance();

    ViewGroup companionView = findViewById(R.id.companionAdSlotFrame);
    final CompanionAdSlot companionAdSlot = sdkFactory.createCompanionAdSlot();
    companionAdSlot.setContainer(companionView);
    companionAdSlot.setSize(640, 640);

    connection =
        new ServiceConnection() {
          @Override
          public void onServiceConnected(ComponentName name, IBinder binder) {
            boundService = ((AudioPlayerService.ServiceBinder) binder).getBoundService();
            boundService.addCompanionAdSlot(companionAdSlot);
            boundService.initializeAds();
          }
          ...
        };
    ...
    bindService(intent, connection, Context.BIND_AUTO_CREATE);
  }
  ...
}

در صورت بروز مشکل می‌توانید پیاده‌سازی خود را با مثال پخش کننده صوتی مقایسه کنید. برای سؤالات بیشتر در مورد پخش آگهی های صوتی پس زمینه، لطفاً برای پشتیبانی به انجمن IMA SDK مراجعه کنید.