Pierwsze kroki z rozszerzeniem ExoPlayer IMA

ExoPlayer to odtwarzacz multimedialny na Androida. Z tego przewodnika dowiesz się, jak używać rozszerzenia ExoPlayer IMA, które zawiera pakiet IMA DAI SDK, do żądania i odtwarzania strumienia multimediów zarówno z reklamami, jak i treściami.

Oto kilka zalet tego rozszerzenia:

• Upraszcza kod potrzebny do integracji IMA z funkcjami.
• Krótszy czas programowania potrzebny do aktualizacji do nowych wersji IMA.

Rozszerzenie ExoPlayer IMA obsługuje protokoły strumieniowania HLS i DASH. Oto podsumowanie:

Obsługa strumienia danych z rozszerzenia ExoPlayer-IMA
	Transmisja na żywo	Strumienie VOD
HLS
DASH

Transmisje na żywo DASH są obsługiwane na urządzeniach ExoPlayer-IMA w wersji 1.1.0 i nowszych.

Ten przewodnik jest oparty na przewodniku ExoPlayer i pokazuje, jak utworzyć pełną aplikację i zintegrować rozszerzenie. Przykład z pełną przykładową aplikacją znajdziesz w witrynie ExoPlayerExample na GitHubie.

Ważne: rozszerzenie ExoPlayer IMA zależy od rozszerzenia ExoPlayer. Jeśli wolisz korzystać z innego odtwarzacza, postępuj zgodnie z instrukcjami w przewodniku dla początkujących, by zintegrować pakiet IMA DAI SDK ze swoją aplikacją.

Wymagania wstępne

• Android Studio,
• AndroidX Media3 ExoPlayer w wersji 1.0.0 lub nowszej na potrzeby DAI.

Tworzenie nowego projektu w Android Studio

Aby utworzyć projekt w Android Studio, wykonaj te czynności:

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

• Na stronie Skonfiguruj projekt nadaj projektowi nazwę i wybierz język Java.

  Uwaga: pakiet IMA DAI SDK jest zgodny z platformą Kotlin. Jednak w przykładzie omówionym w tym przewodniku użyto języka Java.

• Kliknij Zakończ.

Dodawanie rozszerzenia ExoPlayer IMA do projektu

W sekcji dependencies dodaj importy rozszerzenia do pliku build.gradle na poziomie aplikacji.

Skonfiguruj w aplikacji i włącz multidex. Jest to konieczne ze względu na rozmiar rozszerzenia i wymagane w przypadku aplikacji, w których minSdkVersion ma Android 4.4W (poziom interfejsu API 20) lub niższy.

Oto przykład:

app/build.gradle

android {

  ...

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 19
      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 wysyłania żądań 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>

Dodaj deklaracje intencji

Jeśli Twoja aplikacja jest kierowana na Androida 11 (poziom interfejsu API 30) lub nowszego, bieżąca i nowsze wersje pakietu IMA DAI SDK wymagają wyraźnej deklaracji zamiaru otwierania linków internetowych. Dodaj ten fragment do pliku manifestu aplikacji, aby umożliwić klikanie reklam (użytkownicy klikający przycisk Więcej informacji).

Uwaga: kolejne wersje pakietu IMA DAI SDK będą automatycznie uwzględniać te deklaracje i zostaną scalone z plikiem 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 do użycia przez ExoPlayer.

Zmień androidx.constraintlayout.widget.ConstraintLayout na LinearLayout, które 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ładowego strumienia IMA znajdziesz przykładowe zasoby strumienia umożliwiające przetestowanie projektu. Informacje o konfigurowaniu własnych strumieni znajdziesz też w sekcji poświęconej Ad Managerowi na temat DAI.

Ten krok pokazuje konfigurowanie transmisji na żywo, ale rozszerzenie ExoPlayer IMA obsługuje też strumienie VOD z dynamicznym wstawianiem reklam. Zapoznaj się z krokiem dotyczącym strumieni wideo na żądanie (VOD), aby dowiedzieć się, jakie zmiany wymaga Twoja aplikacja, aby obsługiwać strumienie VOD.

Importowanie rozszerzenia ExoPlayer IMA

Dodaj instrukcje importu dla rozszerzenia ExoPlayer.

Dodaj do MyActivity.java te zmienne prywatne:

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

Dodaj klucz zasobu Big Buck Bunny (Live), aby przetestować ten strumień. Więcej strumieni możesz przetestować na stronie przykładowego strumienia 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

Zastąp metodę onCreate, aby znaleźć PlayerView i sprawdzić zapisany obiekt AdsLoader.State, którego można użyć podczas inicjowania obiektu adsLoader.

Włącz też Multidex, jeśli jest to wymagane przez liczbę metod aplikacji i minSdkVersion (jak wyjaśniono 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);
      }
    }
  }

}

Dodaj metody inicjowania odtwarzacza

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

• Utwórz instancję AdsLoader.
• Utwórz ExoPlayer.
• Utwórz MediaItem z kluczem pliku transmisji na żywo.
• Ustaw MediaItem na odtwarzacz.

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

• Przykładem technologii SSAI jest DAI w usłudze Google Ad Manager .
• Implementacja rozszerzenia IMA ExoPlayer z tego przewodnika została opracowana specjalnie pod kątem współpracy z DAI w usłudze Ad Manager. Rozszerzenia ExoPlayer IMA obsługują również inne instancje SSAI, np. Google Cloud Platform, których nie pokazano 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ę zwalniania odtwarzacza

Dodaj metodę zwalniania odtwarzacza w tej sekwencji:

• Ustaw odniesienia do odtwarzacza na null i zwolnij jego zasoby.
• Zwolnij stan elementu 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ń graczy

Na koniec utwórz wywołania zwrotne zdarzeń cyklu życia aktywności w celu obsługi odtwarzania strumienia.

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

• onStart()
• onStop()

Aby obsługiwać pakiet Android SDK w wersji starszej niż 24: – onResume() – onPause()

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

Ważne: ten przykład dotyczy obsługi zarówno pakietu SDK do Androida w wersji 24 lub nowszej, jak i wersji starszej niż 24. Użyj onStart()/onStop() w przypadku pakietu Android SDK w wersji 24 lub nowszej i onResume()/onPause() w przypadku obsługi wersji starszych niż 24.

W tym kroku używane jest też zdarzenie onSaveInstanceState() do próby zapisania obiektu 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 jest wymagana do odtwarzania treści VOD z reklamami, musisz wykonać te czynności:

1. Dodaj CMS ID i Video ID w przypadku strumienia testowego VOD.
2. Utwórz identyfikator URI VOD typu 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. Zamawiasz i odtwarzasz strumień multimediów za pomocą rozszerzenia ExoPlayer IMA. Pełny kod znajdziesz na przykładach DAI na Androidzie na GitHubie.