Obsługa reklam audio w tle

Ten przewodnik jest przeznaczony dla wydawców, którzy chcą wczytywać reklamy audio w swoich aplikacjach na Androida.

Wymagania wstępne

  • Pakiet IMA Android SDK w wersji 3.16.1 lub nowszej.

Jeśli wydawcy nie mają jeszcze aplikacji z odtwarzaczem audio, zalecamy, aby zaczęli od przykładu odtwarzacza audio na GitHubie. W tym przykładzie jako odtwarzacza na pierwszym planie użyto ExoPlayera. W pozostałej części tego przewodnika opisujemy funkcje niezbędne do odtwarzania reklam IMA w tle.

Dodawanie do aplikacji odtwarzania reklam w tle

Aby odtwarzanie muzyki i reklam audio było kontynuowane, gdy aplikacja działa w tle, możesz utworzyć komponent Service zawierający niestandardowy odtwarzacz audio i moduł wczytywania reklam.

Jeśli Twoja aplikacja ma komponenty MainActivity i AudioPlayerService do odtwarzania dźwięku, możesz zmodyfikować plik AndroidManifest.xml w sposób pokazany poniżej:

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

W usłudze możesz utworzyć niestandardowy odtwarzacz audio, który może być dowolnym odtwarzaczem multimediów, o ile implementuje też interfejs VideoAdPlayer do interakcji z pakietem IMA SDK.

W pakiecie IMA SDK w wersji 3.16.1 dodano nową funkcję createAudioAdDisplayContainer, która umożliwia utworzenie specjalnego kontenera dla modułu wczytywania reklam, aby mógł on wysyłać żądania reklam audio.

Poniższy fragment kodu pokazuje przykład komponentu AudioPlayerService do inicjowania i wysyłania żądań reklam 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);
  }
  ...
}

Używanie reklam z miejscami na reklamy towarzyszące

Reklamy możesz inicjować z miejscami na reklamy towarzyszące lub bez nich. Jeśli zdecydujesz się renderować reklamy towarzyszące, musisz zapewnić dostęp komponentu AudioPlayerService do klasy MainActivity za pomocą bindera usługi, jak pokazano poniżej:

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

Możesz wywołać funkcję addCompanionAdSlot() i przekazać kontener interfejsu użytkownika do renderowania reklam towarzyszących podczas inicjowania reklam z klasy 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);
  }
  ...
}

Jeśli napotkasz problem, możesz porównać swoją implementację z przykładem odtwarzacza audio. Jeśli masz dodatkowe pytania dotyczące odtwarzania reklam audio w tle, skontaktuj się z zespołem pomocy w Centrum pomocy Ad Managera.