ExoPlayer to odtwarzacz multimediów na poziomie aplikacji na Androida. Z tego przewodnika dowiesz się, jak używać rozszerzenia IMA ExoPlayer, które opakowuje pakiet IMA DAI SDK, do wysyłania żądań strumienia multimediów z reklamami i treściami oraz odtwarzania takiego strumienia.
Oto niektóre zalety tego rozszerzenia:
- Upraszcza kod potrzebny do integracji IMA z funkcjami.
- Skraca czas potrzebny na aktualizację do nowych wersji pakietu IMA.
Rozszerzenie IMA ExoPlayera obsługuje protokoły strumieniowego przesyłania HLS i DASH. Oto podsumowanie:
Obsługa strumieni rozszerzenia ExoPlayer-IMA | ||
---|---|---|
Transmisja na żywo | Strumienie VOD | |
HLS | ![]() |
![]() |
DASH | ![]() |
![]() |
Transmisje na żywo DASH są obsługiwane w przypadku ExoPlayer-IMA w wersji 1.1.0 lub nowszej.
Ten przewodnik jest oparty na przewodniku po ExoPlayerze i pokazuje, jak utworzyć pełną aplikację i zintegrować rozszerzenie. Przykład z kompletną przykładową aplikacją znajdziesz w ExoPlayerExample
w GitHubie.
Wymagania wstępne
- Android Studio
- AndroidX Media3 ExoPlayer w wersji 1.0.0 lub nowszej do obsługi DAI.
Tworzenie nowego projektu Android Studio
Aby utworzyć projekt Android Studio, wykonaj te czynności:
- Uruchom Android Studio.
- Kliknij Rozpocznij nowy projekt w Android Studio.
- Na stronie Wybierz projekt kliknij szablon Brak aktywności.
- Kliknij Dalej.
Na stronie Skonfiguruj projekt nadaj projektowi nazwę i wybierz język Java.
Kliknij Zakończ.
Dodawanie do projektu rozszerzenia ExoPlayer IMA
Dodaj instrukcje importu rozszerzenia do pliku build.gradle na poziomie aplikacji w sekcji dependencies
.
Skonfiguruj aplikację i włącz multidex. Jest to konieczne ze względu na rozmiar rozszerzenia i wymagane w przypadku aplikacji, w których parametr minSdkVersion
ma wartość Android 4.4W (poziom API 20) lub niższą.
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.7.1' implementation 'androidx.media3:media3-exoplayer:1.7.1' implementation 'androidx.media3:media3-exoplayer-hls:1.7.1' implementation 'androidx.media3:media3-exoplayer-dash:1.7.1' // Adding the ExoPlayer IMA extension for ads will also include the IMA // SDK as a dependency. implementation 'androidx.media3:media3-exoplayer-ima:1.7.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 intencji
Jeśli Twoja aplikacja jest kierowana na Androida 11 (API na poziomie 30) lub nowszego, bieżące i ostatnie wersje pakietu IMA DAI SDK wymagają wyraźnego zadeklarowania zamiaru otwierania linków internetowych. Aby włączyć klikanie reklam (użytkownicy klikający przycisk Więcej informacji), dodaj do pliku manifestu aplikacji ten fragment kodu:
<?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 ExoPlayera
Utwórz obiekt PlayerView
, który będzie używany przez ExoPlayera.
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 z przykładowym strumieniem 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 Managera dotyczącej DAI.
Ten krok pokazuje, jak skonfigurować transmisję na żywo, ale rozszerzenie ExoPlayer IMA obsługuje też strumienie VOD DAI. W kroku dotyczącym strumieni wideo na żądanie znajdziesz informacje o tym, jakie zmiany musisz wprowadzić w aplikacji, aby obsługiwała strumienie VOD.
Importowanie rozszerzenia IMA odtwarzacza ExoPlayer
Dodaj instrukcje importu dla rozszerzenia ExoPlayer.
Dodaj do pliku MyActivity.java
te zmienne prywatne:
PlayerView
ExoPlayer
ImaServerSideAdInsertionMediaSource.AdsLoader
ImaServerSideAdInsertionMediaSource.AdsLoader.State
Dodaj klucz pliku strumienia HLS Big Buck Bunny (Live), aby przetestować ten strumień. Więcej strumieni do testowania znajdziesz na stronie z przykładowymi strumieniami IMA.
Utwórz KEY_ADS_LOADER_STATE
stałąAdsLoader
, aby zapisywać i pobierać AdsLoader
stanAdsLoader
.
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; import com.google.ads.interactivemedia.v3.api.ImaSdkFactory; import com.google.ads.interactivemedia.v3.api.ImaSdkSettings; ... 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 ImaSdkSettings imaSdkSettings; private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader; private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState; }
Tworzenie instancji adsLoader
Zastąp metodę onCreate
, aby znaleźć PlayerView
i sprawdzić, czy jest 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
(zgodnie z krokiem 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 ImaSdkSettings imaSdkSettings; 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); // Initialize the IMA SDK as early as possible when the app starts. If your app already // overrides Application.onCreate(), call this method inside the onCreate() method. // https://developer.android.com/topic/performance/vitals/launch-time#app-creation ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings()); 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); } } } private ImaSdkSettings getImaSdkSettings() { if (imaSdkSettings == null) { imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings(); // Set any IMA SDK settings here. } return imaSdkSettings; } }
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 zasobu transmisji na żywo. - Ustaw
MediaItem
na odtwarzaczu.
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 .setImaSdkSettings(getImaSdkSettings()) .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); } }
Dodawanie metody zwalniania odtwarzacza
Dodaj metodę zwalniania odtwarzacza w tej kolejności:
- Ustaw odwołania do odtwarzacza na wartość null i zwolnij zasoby odtwarzacza.
- 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ługiwać odtwarzanie strumienia.
Aby obsługiwać pakiet Android SDK w wersji 24 lub nowszej:
Aby obsługiwać wersje pakietu SDK na Androida starsze niż 24:
onStart()
i onResume()
są mapowane na playerView.onResume()
, a onStop()
i onPause()
są mapowane na playerView.onPause()
.
W tym kroku używane jest też zdarzenie
onSaveInstanceState()
do próby zapisania 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()); } } ... }
Konfigurowanie strumienia VOD (opcjonalnie)
Jeśli Twoja aplikacja musi odtwarzać treści VOD z reklamami, musisz wykonać te czynności:
- Dodaj
CMS ID
iVideo ID
w przypadku testowego strumienia VOD. - Utwórz identyfikator URI VOD SSAI za pomocą
ImaServerSideAdInsertionUriBuilder()
. - 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 wysyłasz żądanie strumienia multimediów i odtwarzasz go za pomocą rozszerzenia ExoPlayer IMA. Pełny kod znajdziesz w przykładowych aplikacjach DAI na Androida w GitHubie.