ExoPlayer ist ein Mediaplayer für Android auf Anwendungsebene. In diesem Leitfaden wird beschrieben, wie Sie mit der ExoPlayer-IMA-Erweiterung, die das IMA Android DAI SDK umschließt, einen Mediastream mit Anzeigen und Content anfordern und wiedergeben können.
Dies sind einige der Vorteile der Erweiterung:
- Vereinfacht den Code, der für die Integration von IMA mit Funktionen erforderlich ist.
- verkürzt die Entwicklungszeit für die Aktualisierung auf neue Versionen von IMA
Die ExoPlayer IMA-Erweiterung unterstützt die Streaming-Protokolle HLS und DASH. Hier ist eine Zusammenfassung:
Streamunterstützung für ExoPlayer-IMA-Erweiterungen | ||
---|---|---|
Livestream | VOD-Streams | |
HLS | ||
DASH |
DASH-Livestreams werden ab ExoPlayer-IMA-Version 1.1.0 unterstützt.
Dieser Leitfaden basiert auf dem ExoPlayer-Leitfaden und zeigt, wie Sie eine vollständige Anwendung erstellen und die Erweiterung integrieren. Ein Beispiel mit einer vollständigen Beispielanwendung finden Sie unter ExoPlayerExample
von GitHub.
Voraussetzungen
- Android Studio
- AndroidX Media3 ExoPlayer Version 1.0.0 oder höher zur Unterstützung der dynamischen Anzeigenbereitstellung
Ein neues Android Studio-Projekt erstellen
So erstellen Sie ein Android Studio-Projekt:
- Starte Android Studio.
- Wählen Sie Start a new Android Studio Project (Neues Android Studio-Projekt starten) aus.
- Wählen Sie auf der Seite Projekt auswählen die Vorlage No Activity (Keine Aktivität) aus.
- Klicke auf Weiter.
Benennen Sie Ihr Projekt auf der Seite Projekt konfigurieren und wählen Sie als Sprache Java aus.
Klicken Sie auf Fertigstellen.
ExoPlayer-IMA-Erweiterung zum Projekt hinzufügen
Fügen Sie der Datei build.gradle auf Anwendungsebene im Abschnitt dependencies
Importe für die Erweiterung hinzu.
Konfigurieren Sie Ihre Anwendung und aktivieren Sie multidex. Das ist aufgrund der Größe der Erweiterung erforderlich und bei Apps erforderlich, in denen minSdkVersion
auf Android 4.4W (API-Level 20) oder niedriger festgelegt ist.
Beispiel:
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' }
Fügen Sie die Nutzerberechtigungen hinzu, die vom IMA SDK zum Anfordern von Anzeigen benötigt werden:
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 SDK --> <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> ... </manifest>
Intent-Deklarationen hinzufügen
Wenn Ihre App auf Android 11 (API-Level 30) oder höher ausgerichtet ist, ist für die aktuelle und aktuelle Version des IMA SDK eine ausdrückliche Absichtserklärung zum Öffnen von Weblinks erforderlich. Fügen Sie der Manifestdatei Ihrer App das folgende Snippet hinzu, um Klicks auf Anzeigen zu ermöglichen (Nutzer klicken auf die Schaltfläche Weitere Informationen).
<?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>
Benutzeroberfläche von ExoPlayer einrichten
Erstellen Sie das PlayerView
-Objekt, das von ExoPlayer verwendet werden soll.
Ändern Sie androidx.constraintlayout.widget.ConstraintLayout
in LinearLayout
, was für die ExoPlayer-IMA-Erweiterung empfohlen wird.
Beispiel:
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>
Streamparameter hinzufügen
Auf der Seite mit Beispielstream-Assets für das IMA-Beispiel finden Sie Beispiele für Stream-Assets, mit denen Sie Ihr Projekt testen können. Informationen zum Einrichten eigener Streams finden Sie im Ad Manager-Abschnitt zur dynamischen Anzeigenbereitstellung.
In diesem Schritt wird die Einrichtung eines Livestreams veranschaulicht. Die ExoPlayer IMA-Erweiterung unterstützt aber auch VOD-Streams für die dynamische Anzeigenbereitstellung. Im Schritt für Video-on-Demand-Streams (VOD) erfährst du, welche Änderungen deine App zur Verarbeitung von VOD-Streams benötigt.
ExoPlayer-IMA-Erweiterung importieren
Fügen Sie die Importanweisungen für die ExoPlayer-Erweiterung hinzu.
Fügen Sie MyActivity.java
die folgenden privaten Variablen hinzu:
PlayerView
ExoPlayer
ImaServerSideAdInsertionMediaSource.AdsLoader
ImaServerSideAdInsertionMediaSource.AdsLoader.State
Füge den Asset-Schlüssel des HLS-Streams Big Buck Bunny (Live) hinzu, um ihn mit diesem Stream zu testen. Auf der Beispiel-Stream-Seite von IMA sind weitere Streams zum Testen verfügbar.
Erstellen Sie eine KEY_ADS_LOADER_STATE
-Konstante, um den Status AdsLoader
zu speichern und abzurufen.
Beispiel:
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; }
adsLoader
-Instanz erstellen
Überschreiben Sie die Methode onCreate
, um die PlayerView
zu finden und nach einem gespeicherten AdsLoader.State
zu suchen, der beim Initiieren des adsLoader
-Objekts verwendet werden kann.
Aktivieren Sie außerdem Multidex, wenn dies aufgrund der Methodenanzahl und minSdkVersion
Ihrer Anwendung erforderlich ist (wie in Schritt 2 erläutert).
Beispiel:
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.CREATOR.fromBundle( adsLoaderStateBundle); } } } }
Methoden zum Initialisieren des Players hinzufügen
Füge eine Methode zur Initialisierung des Players hinzu und führe die folgenden Schritte aus:
- Erstellen Sie eine
AdsLoader
-Instanz. - Erstellen Sie
ExoPlayer
. - Erstelle eine
MediaItem
mit dem Asset-Schlüssel des Livestreams. - Lege für
MediaItem
deinen Player fest.
Beispiel:
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); } }
Methode zum Loslassen des Players hinzufügen
Füge eine Methode hinzu, um den Player in dieser Sequenz freizugeben:
- Setze die Spielerreferenzen auf null und gib die Ressourcen des Spielers frei.
- Geben Sie den Status von
adsLoader
frei.
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(); }
Spielerereignisse verarbeiten
Erstellen Sie abschließend Callbacks für die Lebenszyklusereignisse der Aktivität, um die Streamwiedergabe zu verarbeiten.
So unterstützen Sie das Android SDK 24 oder höher:
Zur Unterstützung von Android SDK-Versionen unter 24:
– onResume()
– onPause()
onStart()
und onResume()
sind playerView.onResume()
und onStop()
und onPause()
playerView.onPause()
zugeordnet.
In diesem Schritt wird auch das Ereignis onSaveInstanceState()
verwendet, um das adsLoaderState
zu speichern.
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()); } } ... }
VOD-Stream einrichten (optional)
Wenn in Ihrer App VOD-Inhalte mit Anzeigen wiedergegeben werden müssen, gehen Sie so vor:
- Füge
CMS ID
undVideo ID
für einen VOD-Teststream hinzu. - Erstellen Sie mit
ImaServerSideAdInsertionUriBuilder()
einen SSAI-VOD-URI. - Verwende diesen neuen URI als Medienelement deines Players.
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 = "2528370"; 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); }
Fertig! Sie fordern jetzt einen Mediastream mit der ExoPlayer IMA-Erweiterung an und spielen ihn ab. Den vollständigen Code finden Sie in den Beispielen für die dynamische Anzeigenbereitstellung in Android auf GitHub.