پشتیبانی از تبلیغات صوتی پس زمینه

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

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

پیش‌نیازها

• IMA Android SDK نسخه ۳.۱۶.۱ یا بالاتر.

اگر ناشران در حال حاضر برنامه پخش‌کننده صوتی ندارند، به عنوان نقطه شروع به مثال پخش‌کننده صوتی در گیت‌هاب مراجعه کنند. این مثال از 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 SDK نیز پیاده‌سازی کند.

IMA SDK نسخه ۳.۱۶.۱ یک تابع جدید به 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 از طریق یک service binder فراهم کنید، همانطور که در زیر نشان داده شده است:

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

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