تشغيل إعلان على الراديو في الخلفية

هذا الدليل مخصَّص للناشرين المهتمين بتحميل الإعلانات الصوتية إلى تطبيقات Android الخاصة بهم.

ملاحظة مهمة: لا ننصح بتشغيل إعلانات الفيديو في وضع الخلفية.

المتطلبات الأساسية

• حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لنظام التشغيل Android، الإصدار 3.16.1 أو إصدار أحدث

ننصح الناشرين بالاطّلاع على مثال على مشغّل الصوت في github كنقطة بداية إذا لم يكن لديهم حاليًا تطبيق مشغِّل صوت. يستخدم هذا المثال ExoPlayer كمشغّل في المقدّمة. سيوضّح الجزء المتبقي من هذا الدليل الميزات اللازمة لتشغيل الصوت في الخلفية لإعلانات الوسائط التفاعلية.

نقطة رئيسية: ينفِّذ المثال الأساسي إضافة 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 من أجل التفاعل مع حزمة تطوير البرامج لإعلانات الوسائط التفاعلية.

أضاف الإصدار 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);
  }
  ...
}

يمكنك مقارنة عملية التنفيذ التي أجريتها مع مثال مشغّل الصوت إذا واجهتك مشكلة. لمزيد من الأسئلة حول تشغيل الإعلانات الصوتية في الخلفية، يُرجى التواصل في منتدى أداة تطوير البرامج لإعلانات الوسائط التفاعلية للحصول على الدعم.