Mit IMA SDKs kannst du ganz einfach Multimedia-Anzeigen in deine Websites und Apps einbinden. Mit IMA SDKs können Anzeigen von jedem VAST-kompatiblen Ad-Server angefordert und die Anzeigenwiedergabe in Ihren Apps verwaltet werden. Mit clientseitigen IMA SDKs behalten Sie die Kontrolle über die Videowiedergabe von Inhalten, während das SDK die Anzeigenwiedergabe übernimmt. Anzeigen werden in einem separaten Videoplayer wiedergegeben, der über dem Videoplayer der App angezeigt wird.
In dieser Anleitung wird gezeigt, wie du das IMA SDK mithilfe der ExoPlayer IMA-Erweiterung in ein leeres Android Studio-Projekt einbindest. Wenn Sie sich eine fertige Beispielintegration ansehen oder nachvollziehen möchten, laden Sie BasicExample von GitHub herunter.
IMA-Client – Übersicht
Die clientseitige Implementierung von IMA umfasst vier Haupt-SDK-Komponenten, die in diesem Leitfaden veranschaulicht werden:
AdDisplayContainer
: Ein Containerobjekt, das angibt, wo IMA UI-Elemente für Anzeigen rendert und die Sichtbarkeit misst, einschließlich Active View und Open Measurement.AdsLoader
: Ein Objekt, das Anzeigen anfordert und Ereignisse aus Antworten auf Anzeigenanfragen verarbeitet. Sie sollten nur einen Anzeigen-Lademechanismus instanziieren, der während der gesamten Lebensdauer der Anwendung wiederverwendet werden kann.AdsRequest
: Objekt, das eine Anzeigenanfrage definiert. In Anzeigenanfragen werden die URL für das VAST-Anzeigen-Tag sowie zusätzliche Parameter wie Anzeigendimensionen angegeben.AdsManager
: Ein Objekt, das die Antwort auf die Anzeigenanfrage enthält, die Anzeigenwiedergabe steuert und auf vom SDK ausgelöste Anzeigenereignisse wartet.
Vorbereitung
Bevor Sie beginnen, benötigen Sie Android Studio 3.0 oder höher.
1. 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 Choose your project (Projekt auswählen) die Vorlage Empty Activity (Leere Aktivität) aus.
- Klicken Sie auf Weiter.
- Geben Sie auf der Seite Projekt konfigurieren einen Namen für das Projekt ein und wählen Sie „Java“ als Sprache aus.
- Klicken Sie auf Fertig.
2. ExoPlayer IMA-Erweiterung zum Projekt hinzufügen
Fügen Sie zuerst in der Datei build.gradle auf Anwendungsebene dem Abschnitt „dependencies“ Importe für die Erweiterung hinzu. Aufgrund der Größe der ExoPlayer-IMA-Erweiterung solltest du hier Multidex implementieren und aktivieren. Dies ist für Apps erforderlich, bei denen minSdkVersion
auf 20 oder weniger festgelegt ist.
Fügen Sie außerdem neue compileOptions
hinzu, um die Informationen zur Kompatibilität der Java-Version anzugeben.
android { namespace 'com.google.ads.interactivemedia.v3.samples.exoplayerexample' compileSdkVersion 34 compileOptions { sourceCompatibility JavaVersion.VERSION_17 targetCompatibility JavaVersion.VERSION_17 } } defaultConfig { applicationId "com.google.ads.interactivemedia.v3.samples.exoplayerexample" 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.3.1' implementation 'androidx.media3:media3-exoplayer:1.3.1' implementation 'androidx.media3:media3-exoplayer-ima:1.3.1' ... }
Fügen Sie die Nutzerberechtigungen hinzu, die vom IMA SDK für das 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>
Absichtserklärungen hinzufügen
Wenn Ihre App auf Android 11 (API-Level 30) oder höher ausgerichtet ist, erfordern die aktuelle und die letzten Versionen des IMA SDK eine ausdrückliche Erklärung, dass Sie Weblinks öffnen möchten. Fügen Sie der Manifestdatei Ihrer App das folgende Snippet hinzu, um Klicks auf Anzeigen zu aktivieren (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>
3. Container für die Anzeigen-UI erstellen
Erstelle die Ansicht, die als ExoPlayer-PlayerView verwendet werden soll, indem du ein StyledPlayerView
-Objekt mit einer geeigneten ID erstellst. Ändern Sie auch die androidx.constraintlayout.widget.ConstraintLayout
in eine LinearLayout
.
<?xml version="1.0" encoding="utf-8"?> <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" xmlns:app="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools" android:layout_width="match_parent" android:layout_height="match_parent" tools:context=".MainActivity"> <androidx.media3.ui.PlayerView android:id="@+id/player_view" android:layout_width="match_parent" android:layout_height="wrap_content" /> </LinearLayout>
4. Fügen Sie die Inhalts- und Anzeigen-Tag-URL für die Anzeigenanfrage hinzu.
Fügen Sie strings.xml
Einträge hinzu, um die URL des Inhalts und die URL des VAST-Anzeigen-Tags zu speichern.
<resources> <string name="app_name">Your_Project_Name</string> <string name="content_url"><![CDATA[https://storage.googleapis.com/gvabox/media/samples/stock.mp4]]></string> <string name="ad_tag_url"><![CDATA[https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/single_ad_samples&sz=640x480&cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=]]></string> </resources>
5. ExoPlayer IMA-Erweiterung importieren
Fügen Sie die Importanweisungen für die ExoPlayer-Erweiterung hinzu. Aktualisieren Sie dann die Klasse MainActivity
, um Activity
zu erweitern, indem Sie private Variablen für PlayerView
, SimpleExoPlayer
und ImaAdsLoader
hinzufügen.
import android.app.Activity; import android.net.Uri; import android.os.Bundle; 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.ImaAdsLoader; import androidx.media3.exoplayer.source.DefaultMediaSourceFactory; import androidx.media3.exoplayer.source.MediaSource; import androidx.media3.ui.PlayerView; import androidx.multidex.MultiDex; ... public class MainActivity extends Activity { private PlayerView playerView; private ExoPlayer player; private ImaAdsLoader adsLoader; }
6. adsLoader
-Instanz erstellen
Überschreiben Sie die onCreate
-Methode und fügen Sie die erforderlichen Variablenzuweisungen hinzu, um ein neues adsLoader
-Objekt mit der Anzeigen-Tag-URL zu erstellen.
... public class MainActivity extends Activity { private PlayerView playerView; private ExoPlayer player; private ImaAdsLoader adsLoader; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); MultiDex.install(this); playerView = findViewById(R.id.player_view); // Create an AdsLoader. adsLoader = new ImaAdsLoader.Builder(/* context= */ this) .setAdEventListener(buildAdEventListener()) .build(); } public AdEvent.AdEventListener buildAdEventListener() { AdEvent.AdEventListener imaAdEventListener = event -> { AdEvent.AdEventType eventType = event.getType(); // Log IMA events for debugging. // The ExoPlayer IMA extension already handles IMA events and does not need anything // additional here to function. }; return imaAdEventListener; } }
7. Player initialisieren und freigeben
Füge Methoden zum Initialisieren und Freigeben des Players hinzu. Erstellen Sie in der Methode „initialize“ die SimpleExoPlayer
. Erstelle dann die AdsMediaSource
und setze sie für den Player ein.
public class MainActivity extends Activity { ... private void releasePlayer() { adsLoader.setPlayer(null); playerView.setPlayer(null); player.release(); player = null; } private void initializePlayer() { // Set up the factory for media sources, passing the ads loader and ad view providers. DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this); MediaSource.Factory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory) .setLocalAdInsertionComponents(unusedAdTagUri -> adsLoader, playerView); // 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); // Create the MediaItem to play, specifying the content URI and ad tag URI. Uri contentUri = Uri.parse(getString(R.string.content_url)); Uri adTagUri = Uri.parse(getString(R.string.ad_tag_url)); MediaItem mediaItem = new MediaItem.Builder() .setUri(contentUri) .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build()) .build(); // Prepare the content and ad to be played with the SimpleExoPlayer. player.setMediaItem(mediaItem); player.prepare(); // Set PlayWhenReady. If true, content and ads will autoplay. player.setPlayWhenReady(false); } }
8. Spielerereignisse verarbeiten
Erstelle abschließend Callbacks für die Lebenszyklusereignisse des Spielers:
onStart
onResume
onStop
onPause
onDestroy
public class MainActivity extends Activity { private PlayerView playerView; private SimpleExoPlayer player; private ImaAdsLoader adsLoader; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_my); playerView = findViewById(R.id.player_view); // Create an AdsLoader. adsLoader = new ImaAdsLoader.Builder(/* context= */ this) .setAdEventListener(buildAdEventListener()) .build(); } @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 protected void onDestroy() { super.onDestroy(); adsLoader.release(); } ... }
Geschafft! Sie fordern jetzt Anzeigen über das IMA SDK an und schalten sie. Weitere Informationen zu den SDK-Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.