پشتیبانی از آگهی‌های صوتی پس‌زمینه

این راهنما برای ناشرانی است که به بار کردن آگهی‌های صوتی در برنامه‌های Android خود علاقه‌مند هستند.

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

پیش‌نیازها

• کیت توسعه نرم‌افزار IMA Android نسخه ۳.۱۶.۱ یا بالاتر.

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

نکته کلیدی: مثال پایه افزونه 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» پیاده‌سازی کند.

در نسخه ۳.۱۶.۱ از «کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی»، تابع جدیدی به‌نام 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);
  }
  ...
}

اگر با مشکلی مواجه شدید، می‌توانید پیاده‌سازی‌تان را با نمونه پخش‌کننده صوتی مقایسه کنید. برای سؤالات بیشتر درباره بازپخش آگهی صوتی پس‌زمینه، ازطریق مرکز راهنمایی Ad Manager با پشتیبانی تماس بگیرید.