Gli SDK IMA semplificano l'integrazione di annunci multimediali nei tuoi siti web e nelle tue app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK lato client IMA, puoi mantenere il controllo della riproduzione dei video dei contenuti, mentre l'SDK gestisce la riproduzione degli annunci. Gli annunci vengono riprodotti in un video player separato posizionato nella parte superiore del video player dei contenuti dell'app.
Questa guida illustra come integrare l'SDK IMA in un progetto Android Studio vuoto utilizzando l'estensione IMA ExoPlayer. Se vuoi visualizzare o seguire un'integrazione di esempio completata, scarica l'elemento BasicExample da GitHub.
Panoramica lato client IMA
L'implementazione lato client IMA implica l'utilizzo di quattro componenti principali dell'SDK, illustrati in questa guida:
AdDisplayContainer
: un oggetto contenitore in cui viene visualizzato gli annunci.AdsLoader
: un oggetto che richiede annunci e gestisce gli eventi dalle risposte alle richieste di annunci. Dovresti intensificare un solo caricatore di annunci, che può essere riutilizzato per tutta la vita dell'applicazione.AdsRequest
: un oggetto che definisce una richiesta di annunci. Le richieste di annunci specificano l'URL del tag annuncio VAST e parametri aggiuntivi, come le dimensioni dell'annuncio.AdsManager
: un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione dell'annuncio e ascolta gli eventi annunci attivati dall'SDK.
Prerequisiti
Prima di iniziare, devi avere Android Studio 3.0 o versioni successive.
1. Creare un nuovo progetto Android Studio
Per creare il tuo progetto Android Studio, completa i seguenti passaggi:
- Avvia Android Studio.
- Seleziona Avvia un nuovo progetto Android Studio.
- Nella pagina Scegli il tuo progetto, seleziona il modello Attività vuota.
- Fai clic su Avanti.
- Nella pagina Configura il tuo progetto, assegna un nome al progetto e seleziona Java per il linguaggio.
- Fai clic su Fine.
2. Aggiungere l'estensione IMA ExoPlayer al progetto
Innanzitutto, nel file build.gradle a livello di applicazione, aggiungi le importazioni dell'estensione alla sezione delle dipendenze. A causa delle dimensioni dell'estensione IMA ExoPlayer, implementa e attiva multidex qui. Questa operazione è necessaria per le app con un valore minSdkVersion
impostato su un valore pari o inferiore a 20.
Inoltre, aggiungi nuovo compileOptions
per specificare le informazioni sulla compatibilità della versione Java.
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' ... }
Aggiungi le autorizzazioni dell'utente richieste dall'SDK IMA per richiedere gli annunci.
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>
Aggiungi dichiarazioni di intent
Se la tua app ha come target Android 11 (livello API 30) o versioni successive, le versioni attuali e recenti dell'SDK IMA richiedono una dichiarazione esplicita di intent per aprire i link web. Aggiungi il seguente snippet al file manifest della tua app per attivare i clickthrough degli annunci (utenti che fanno clic sul pulsante Scopri di più).<?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. Creare il contenitore dell'interfaccia utente degli annunci
Crea la visualizzazione da utilizzare come ExoPlayer PlayerView creando un oggetto StyledPlayerView
con un ID appropriato. Inoltre, modifica
androidx.constraintlayout.widget.ConstraintLayout
in 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. Aggiungi l'URL dei contenuti e l'URL del tag annuncio per la richiesta di annunci
Aggiungi voci a strings.xml
per memorizzare l'URL dei contenuti e l'URL del tag annuncio VAST.
<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. Importare l'estensione IMA di ExoPlayer
Aggiungi le istruzioni di importazione per l'estensione ExoPlayer. Poi, aggiorna la
classe MainActivity
per estendere Activity
aggiungendo variabili private per
PlayerView
, SimpleExoPlayer
e ImaAdsLoader
.
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. Crea un'istanza adsLoader
Sovrascrivi il metodo onCreate
e aggiungi le assegnazioni di variabili richieste per creare un nuovo oggetto adsLoader
con l'URL del tag annuncio.
... 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. Inizializza e rilascia il player
Aggiungi metodi per inizializzare e rilasciare il player. Nel metodo di inizializzazione, crea SimpleExoPlayer
. Quindi, crea il AdsMediaSource
e impostalo sul player.
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. Gestire gli eventi dei giocatori
Infine, crea i callback per gli eventi del ciclo di vita del player:
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(); } ... }
È tutto. Ora richiedi e visualizzi gli annunci con l'SDK IMA. Per scoprire di più sulle funzionalità aggiuntive dell'SDK, consulta le altre guide o gli esempi su GitHub.