Riproduzione di annunci audio in background

Questa guida è rivolta ai publisher interessati a caricare annunci audio nelle loro app per Android.

Importante: sconsigliamo di riprodurre gli annunci video in modalità in background.

Prerequisiti

• SDK IMA per Android versione 3.16.1 o successive.

Se al momento non hai un'app di lettore audio, ti consigliamo di consultare l'esempio di lettore audio su GitHub come punto di partenza. Questo esempio utilizza ExoPlayer come player in primo piano. La parte rimanente di questa guida descrive le funzionalità necessarie per la riproduzione audio in background degli annunci IMA.

Punto chiave: l'esempio di base implementa l'estensione Exoplayer-IMA che gestisce la maggior parte della configurazione dell'SDK IMA. Per questo motivo, l'Esempio di base non può essere utilizzato come punto di partenza per questa guida.

Aggiungere la riproduzione di annunci in background alla tua app

Affinché la riproduzione di musica e annunci audio continui quando l'app è in modalità in background, puoi creare un Service componente contenente un player audio personalizzato e un loader di annunci.

Se la tua app ha un MainActivity e un AudioPlayerService per la riproduzione audio, puoi modificare il file AndroidManifest.xml come mostrato di seguito:

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

Nel servizio puoi creare un player audio personalizzato, che può essere qualsiasi media player, a condizione che implementi anche l'interfaccia VideoAdPlayer per interagire con l'SDK IMA.

L'SDK IMA 3.16.1 ha aggiunto una nuova funzione, createAudioAdDisplayContainer, per creare un contenitore specializzato per consentire a un caricatore di annunci di richiedere annunci audio.

Il seguente snippet di codice mostra un esempio di AudioPlayerService per inizializzare e effettuare richieste di annunci audio.

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

Utilizzare gli annunci con gli slot annunci companion

Puoi inizializzare gli annunci con o senza spazi annunci companion. Se scegli di visualizzare gli annunci di tipo companion, devi fornire l'accesso di AudioPlayerService alla classe MainActivity tramite un binder di servizio, come mostrato di seguito:

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

Puoi chiamare la funzione addCompanionAdSlot() e passare un contenitore dell'interfaccia utente per il rendering degli annunci banner di tipo companion durante l'inizializzazione degli annunci dalla classe 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);
  }
  ...
}

Se riscontri un problema, puoi confrontare la tua implementazione con l'esempio di audio player. Per ulteriori domande sulla riproduzione degli annunci audio in background, rivolgiti al forum dell'SDK IMA per ricevere assistenza.