Pierwsze kroki z rozszerzeniem ExoPlayer IMA

ExoPlayer to odtwarzacz multimediów na poziomie aplikacji na Androida. Z tego przewodnika dowiesz się, jak używać rozszerzenia IMA dla ExoPlayera, które zawiera pakiet IMA DAI SDK, aby żądać i odtwarzać strumień multimediów zawierający reklamy i treści.

Oto kilka zalet rozszerzenia:

• Upraszcza kod potrzebny do zintegrowania IMA z funkcjami.
• Skrócenie czasu potrzebnego na przeniesienie na nowe wersje IMA.

Rozszerzenie ExoPlayer IMA obsługuje protokoły strumieniowego przesyłania danych HLS i DASH. Oto podsumowanie:

Obsługa strumieniowania rozszerzenia ExoPlayer-IMA
	Transmisja na żywo	strumienie VOD,
HLS
DASH

Transmisje na żywo DASH są obsługiwane w ExoPlayer-IMA w wersji 1.1.0 lub nowszej.

Ten przewodnik opiera się na przewodniku ExoPlayer i pokazuje, jak utworzyć pełną aplikację oraz zintegrować rozszerzenie. Pełną przykładową aplikację znajdziesz w ExoPlayerExample na GitHubzie.

Najważniejsza uwaga: rozszerzenie ExoPlayer IMA zależy od ExoPlayera. Jeśli wolisz używać innego odtwarzacza, postępuj zgodnie z przewodnikiem, aby zintegrować pakiet IMA DAI SDK z aplikacją.

Wymagania wstępne

• Android Studio
• AndroidX Media3 ExoPlayer w wersji 1.0.0 lub nowszej w celu obsługi DAI.

Tworzenie nowego projektu w Android Studio

Aby utworzyć projekt w Android Studio:

• Uruchom Android Studio.
• Kliknij Rozpocznij nowy projekt Android Studio.
• Na stronie Wybierz projekt wybierz szablon Brak aktywności.
• Kliknij Dalej.

• Na stronie Skonfiguruj projekt nadaj projektowi nazwę i w sekcji Język wybierz Java.

  Uwaga: pakiet IMA DAI SDK jest zgodny z Kotlinem. Przykład w tym przewodniku korzysta jednak z języka Java.

• Kliknij Zakończ.

Dodawanie rozszerzenia ExoPlayer IMA do projektu

Dodaj importy rozszerzenia do pliku build.gradle na poziomie aplikacji w sekcji dependencies.

Skonfiguruj aplikację i włącz multideksy. Jest to konieczne ze względu na rozmiar rozszerzenia i jest wymagane w przypadku aplikacji z minSdkVersion ustawionym na Androida 4.4W (poziom API 20) lub niższego.

Oto przykład:

app/build.gradle

android {

  ...

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 21
      targetSdkVersion 34
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.1.1'
    implementation 'androidx.media3:media3-exoplayer:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-hls:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-dash:1.1.1'

    // Adding the ExoPlayer IMA extension for ads will also include the IMA
    // SDK as a dependency.
    implementation 'androidx.media3:media3-exoplayer-ima:1.1.1'
}

Dodaj uprawnienia użytkownika wymagane przez pakiet IMA DAI SDK do żądania reklam:

app/src/main/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.project name">

    <!-- Required permissions for the IMA DAI SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

Dodawanie deklaracji zamiaru

Jeśli Twoja aplikacja jest kierowana na Androida 11 (poziom API 30) lub nowszego, obecne i niedawnsze wersje pakietu IMA DAI SDK wymagają wyraźnego zadeklarowania zamiaru otwierania linków internetowych. Aby umożliwić użytkownikom klikanie reklam (czyli klikanie przez nich przycisku Dowiedz się więcej), dodaj do pliku manifestu aplikacji ten fragment kodu.

Uwaga: przyszłe wersje pakietu IMA DAI SDK będą automatycznie zawierać te deklaracje i zostaną scalone z pliku manifestu aplikacji.

  <?xml version="1.0" encoding="utf-8"?>
  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.example.project name">

      ...

    </application>

    <queries>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="https" />
      </intent>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="http" />
      </intent>
    </queries>
  </manifest>

Konfigurowanie interfejsu ExoPlayer

Utwórz obiekt PlayerView, który będzie używany przez ExoPlayer.

Zmień androidx.constraintlayout.widget.ConstraintLayout na LinearLayout, co jest zalecane w przypadku rozszerzenia ExoPlayer IMA.

Oto przykład:

app/src/main/res/layout/activity_my.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:background="@android:color/black"
    android:id="@+id/container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".MyActivity"
    tools:ignore="MergeRootFrame">

    <androidx.media3.ui.PlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</LinearLayout>

Dodawanie parametrów strumienia

Na stronie Przykładowy strumień IMA znajdziesz przykładowe zasoby strumienia, które możesz wykorzystać do testowania projektu. Informacje o konfigurowaniu własnych strumieni znajdziesz też w sekcji Ad Manager dotyczącą DAI.

Ten krok pokazuje konfigurowanie transmisji na żywo, ale rozszerzenie ExoPlayer IMA obsługuje też strumienie VOD DAI. Aby dowiedzieć się, jakie zmiany musisz wprowadzić w aplikacji, aby obsługiwała strumienie VOD, zapoznaj się z instrukcjami dotyczącymi strumieni VOD.

Importowanie rozszerzenia ExoPlayer IMA

Dodaj instrukcje importu rozszerzenia ExoPlayer.

Dodaj do pliku MyActivity.java te zmienne prywatne:

• PlayerView
• ExoPlayer
• ImaServerSideAdInsertionMediaSource.AdsLoader
• ImaServerSideAdInsertionMediaSource.AdsLoader.State

Dodaj klucz zasobu strumienia HLS Big Buck Bunny (Live), aby przetestować ten strumień. Więcej strumieni do testowania znajdziesz na stronie strumieni próbnych IMA.

Utwórz stałą KEY_ADS_LOADER_STATE, aby zapisać i pobrać stan AdsLoader.

Oto przykład:

app/src/main/java/com/example/project name/MyActivity.java

import static androidx.media3.common.C.CONTENT_TYPE_HLS;

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.annotation.OptIn;
import androidx.media3.common.MediaItem;
import androidx.media3.common.util.Util;
import androidx.media3.datasource.DataSource;
import androidx.media3.datasource.DefaultDataSource;
import androidx.media3.exoplayer.ExoPlayer;
import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionMediaSource;
import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.util.EventLogger;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

}

Tworzenie instancji adsLoader

Nadpisz metodę onCreate, aby znaleźć PlayerView, i sprawdź, czy istnieje zapisana wartość AdsLoader.State, której można użyć podczas inicjowania obiektu adsLoader.

Włącz też multidex, jeśli wymaga tego liczba metod w aplikacji i minSdkVersion (jak opisano w kroku 2).

Oto przykład:

app/src/main/java/com/example/project name/MyActivity.java

...

public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

  @Override
  protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_my);
    MultiDex.install(this);

    playerView = findViewById(R.id.player_view);

    // Checks if there is a saved AdsLoader state to be used later when
    // initiating the AdsLoader.
    if (savedInstanceState != null) {
      Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE);
      if (adsLoaderStateBundle != null) {
        adsLoaderState =
            ImaServerSideAdInsertionMediaSource.AdsLoader.State.fromBundle(
                adsLoaderStateBundle);
      }
    }
  }

}

Dodawanie metod inicjowania odtwarzacza

Dodaj metodę inicjowania odtwarzacza i wykonaj te czynności:

• Utwórz instancję AdsLoader.
• Utwórz ExoPlayer.
• Utwórz MediaItem z kluczem zasobu transmisji na żywo.
• Ustaw wartość MediaItem na odtwarzaczu.

Uwaga: w tej sekcji używamy metod o nazwach odwołujących się do koncepcji wstawiania reklam po stronie serwera (SSAI).

• Google Ad Manager DAI to przykład usługi SSAI.
• Implementacja rozszerzenia ExoPlayer IMA opisana w tym przewodniku została zaprojektowana specjalnie do współpracy z dynamicznym wstawianiem reklam Ad Managera. Rozszerzenia ExoPlayer IMA obsługują też inne instancje SSAI, takie jak Google Cloud Platform, które nie są omawiane w tym przewodniku.

Oto przykład:

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

  
  // Create a server side ad insertion (SSAI) AdsLoader.
  private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
    ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
        new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

    // Attempt to set the AdsLoader state if available from a previous session.
    if (adsLoaderState != null) {
      adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
    }

    return adsLoaderBuilder.build();
  }

  private void initializePlayer() {
    adsLoader = createAdsLoader();

    // Set up the factory for media sources, passing the ads loader.
    DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);
    DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory);

    // MediaSource.Factory to create the ad sources for the current player.
    ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
        new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory);

    // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory.
    // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server
    // side inserted ad streams.
    mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);

    // Create an ExoPlayer and set it as the player for content and ads.
    player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
    playerView.setPlayer(player);
    adsLoader.setPlayer(player);

    // Build an IMA SSAI media item to prepare the player with.
    Uri ssaiLiveUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setAssetKey(SAMPLE_ASSET_KEY)
            .setFormat(CONTENT_TYPE_HLS) // Use CONTENT_TYPE_DASH for dash streams.
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiLiveUri);

    // Prepare the content and ad to be played with the ExoPlayer.
    player.setMediaItem(ssaiMediaItem);
    player.prepare();

    // Set PlayWhenReady. If true, content and ads will autoplay.
    player.setPlayWhenReady(false);
  }
}

Dodaj metodę zwalniającą odtwarzacz

Dodaj metodę, aby zwolnić odtwarzacz w tej sekwencji:

• Ustaw odwołania do gracza na wartość null i zwolnij zasoby gracza.
• Zwolnij stan adsLoader.

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

  private void releasePlayer() {
    // Set the player references to null and release the player's resources.
    playerView.setPlayer(null);
    player.release();
    player = null;

    // Release the adsLoader state so that it can be initiated again.
    adsLoaderState = adsLoader.release();
  }

Obsługa zdarzeń odtwarzacza

Na koniec utwórz wywołania zwrotne dla zdarzeń cyklu życia aktywności, aby obsłużyć odtwarzanie strumienia.

Aby obsługiwać pakiet Android SDK w wersji 24 lub nowszej:

• onStart()
• onStop()

Aby obsługiwać wersje pakietu SDK na Androida starsze niż 24: - onResume() - onPause()

onStart() i onResume() mapują się na playerView.onResume(), a onStop() i onPause() na playerView.onPause().

Ważne: ten przykład obsługuje zarówno pakiet SDK Androida w wersji 24 lub nowszej, jak i starsze wersje. Użyj wartości onStart()/onStop(), aby uzyskać obsługę pakietu Android SDK w wersji 24 lub nowszej, oraz onResume()/onPause(), aby uzyskać obsługę wersji starszych niż 24.

W tym kroku użyjemy też zdarzenia onSaveInstanceState(), aby spróbować zapisać adsLoaderState.

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

  @Override
  public void onStart() {
    super.onStart();
    if (Util.SDK_INT > 23) {
      initializePlayer();
      if (playerView != null) {
        playerView.onResume();
      }
    }
  }

  @Override
  public void onResume() {
    super.onResume();
    if (Util.SDK_INT <= 23 || player == null) {
      initializePlayer();
      if (playerView != null) {
        playerView.onResume();
      }
    }
  }

  @Override
  public void onPause() {
    super.onPause();
    if (Util.SDK_INT <= 23) {
      if (playerView != null) {
        playerView.onPause();
      }
      releasePlayer();
    }
  }

  @Override
  public void onStop() {
    super.onStop();
    if (Util.SDK_INT > 23) {
      if (playerView != null) {
        playerView.onPause();
      }
      releasePlayer();
    }
  }

  @Override
  public void onSaveInstanceState(Bundle outState) {
    // Attempts to save the AdsLoader state to handle app backgrounding.
    if (adsLoaderState != null) {
      outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle());
    }
  }

  ...

}

Konfiguracja strumienia VOD (opcjonalnie)

Jeśli Twoja aplikacja wymaga odtwarzania treści VOD z reklamami, musisz wykonać te czynności:

1. Dodaj CMS ID i Video ID do testowego strumienia VOD.
2. Utwórz URI VOD SSAI za pomocą ImaServerSideAdInsertionUriBuilder().
3. Użyj tego nowego identyfikatora URI jako elementu multimedialnego odtwarzacza.

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
  private static final String SAMPLE_CMS_ID = "2548831";
  private static final String SAMPLE_VIDEO_ID = "tears-of-steel";

  ...

  private void initializePlayer() {

     ...

    Uri ssaiVodUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setContentSourceId(SAMPLE_CMS_ID)
            .setVideoId(SAMPLE_VIDEO_ID)
            .setFormat(CONTENT_TYPE_HLS)
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiVodUri);

    // Prepare the content and ad to be played with the ExoPlayer.
    player.setMediaItem(ssaiMediaItem);
    player.prepare();

    // Set PlayWhenReady. If true, content and ads will autoplay.
    player.setPlayWhenReady(false);
  }

Znakomicie. Teraz żądasz i odtwarzasz strumień multimediów za pomocą rozszerzenia ExoPlayer IMA. Aby zobaczyć pełny kod, zapoznaj się z przykładami implementacji DAI na Androida na GitHubie.