Gli SDK IMA semplificano l'integrazione degli annunci multimediali nei siti web e nelle app. Gli SDK IMA possono richiedi annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK IMA lato client, tu mantieni il controllo della riproduzione dei contenuti video, mentre l'SDK gestisce la riproduzione degli annunci. Gli annunci vengono riprodotti in video player separato posizionato sopra il video player di contenuti dell'app.
Questa guida illustra come integrare l'SDK IMA in un progetto Android Studio vuoto utilizzando la proprietà Estensione IMA ExoPlayer. Se vuoi visualizzare o seguire un'integrazione di esempio completata, scarica BasicExample da GitHub.
Panoramica lato client IMA
L'implementazione dell'SDK IMA sul lato client riguarda quattro componenti SDK principali, illustrati in questo guida:
AdDisplayContainer
: Un oggetto contenitore in cui vengono visualizzati gli annunci.AdsLoader
: Un oggetto che richiede annunci e gestisce gli eventi provenienti dalle risposte alle richieste di annunci. Dovresti soltanto creare un'istanza per un caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.AdsRequest
: Un oggetto che definisce una richiesta di annunci. Le richieste di annunci specificano l'URL del tag annuncio VAST, parametri aggiuntivi, come le dimensioni degli annunci.AdsManager
: Un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione dell'annuncio e rimane in ascolto dell'annuncio eventi attivati dall'SDK.
Prerequisiti
Prima di iniziare, devi Android Studio 3.0 o versioni successive.
1. Crea un nuovo progetto Android Studio
Per creare il tuo progetto Android Studio, procedi nel seguente modo:
- 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 progetto, assegna un nome al progetto e seleziona Java per il linguaggio.
- Fai clic su Fine.
2. Aggiungi l'estensione IMA di ExoPlayer al tuo progetto
Innanzitutto, nel file build.gradle a livello di applicazione, aggiungi le importazioni per l'estensione alla
delle dipendenze. A causa delle dimensioni dell'estensione IMA di ExoPlayer, implementa e abilita
multidex. Questa azione è necessaria per le app con minSdkVersion
impostato su 20 o meno.
Inoltre, aggiungi un nuovo compileOptions
per specificare le informazioni sulla compatibilità della versione di 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 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 attuale e recente del Gli SDK IMA richiedono una dichiarazione di intenti esplicita per aprire i link web. Aggiungi il seguente snippet a Il file manifest dell'app per attivare i clickthrough degli annunci (gli 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 vista da utilizzare come PlayerView ExoPlayer mediante la creazione di un'StyledPlayerView
oggetto con un ID appropriato. Modifica anche
androidx.constraintlayout.widget.ConstraintLayout
a 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. Importa l'estensione IMA di ExoPlayer
Aggiungi le istruzioni di importazione per l'estensione ExoPlayer. Quindi, aggiorna
MainActivity
classe 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</span> { private PlayerView playerView; private ExoPlayer player; private ImaAdsLoader adsLoader;</span> }
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. Nella barra di inizializzazione
crea l'SimpleExoPlayer
. Poi, crea l'AdsMediaSource
e lo imposti 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 dei 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 stai richiedendo e mostrando gli annunci con l'SDK IMA. Per saperne di più funzioni dell'SDK, consulta le altre guide o su GitHub.