Inizia a utilizzare l'estensione IMA Exoplayer

Gli SDK IMA semplificano l'integrazione degli annunci multimediali nei tuoi siti web e nelle tue app. Gli SDK IMA possono richiedere annunci da qualsiasi ad server conforme a VAST e gestire la riproduzione degli annunci nelle tue app. Con gli SDK lato client IMA, mantieni 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 sopra il video player dei contenuti dell'app.

Questa guida mostra come integrare l'SDK IMA in un progetto Android Studio vuoto utilizzando l'estensione IMA di ExoPlayer. Se vuoi visualizzare o seguire un'integrazione di esempio completata, scarica BasicExample da GitHub.

Nota: per informazioni sull'integrazione con altre piattaforme o sull'utilizzo degli SDK DAI IMA, consulta gli SDK Interactive Media Ads.

Panoramica della tecnologia IMA lato client

L'implementazione lato client di IMA prevede quattro componenti principali dell'SDK, che vengono illustrati in questa guida:

• AdDisplayContainer: un oggetto contenitore che specifica dove IMA esegue il rendering degli elementi dell'interfaccia utente dell'annuncio e misura la visibilità, incluse Visualizzazione attiva e Open Measurement.
• AdsLoader: un oggetto che richiede annunci e gestisce gli eventi delle risposte alle richieste di annunci. Devi solo inizializzare 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, nonché parametri aggiuntivi, come le dimensioni dell'annuncio.
• AdsManager: un oggetto che contiene la risposta alla richiesta di annunci, controlla la riproduzione degli annunci e ascolta gli eventi correlati agli annunci attivati dall'SDK.

Nota: poiché l'estensione ExoPlayer IMA racchiude l'SDK IMA in questa guida, vengono utilizzati sia AdsRequest sia AdsManager, ma non vengono richiamati esplicitamente.

Prerequisiti

Prima di iniziare, devi avere Android Studio 3.0 o versioni successive.

1. Creare un nuovo progetto Android Studio

Per creare il progetto Android Studio:

1. Avvia Android Studio.
2. Seleziona Avvia un nuovo progetto Android Studio.
3. Nella pagina Scegli il tuo progetto, seleziona il modello Attività vuota.
4. Fai clic su Avanti.
5. Nella pagina Configura il progetto, assegna un nome al progetto e seleziona Java come linguaggio.
   Nota: l'SDK IMA è compatibile con Kotlin. Tuttavia, l'esempio trattato in questa guida utilizza Java.
6. Fai clic su Fine.

2. Aggiungere l'estensione ExoPlayer IMA al progetto

Innanzitutto, nel file build.gradle a livello di applicazione, aggiungi le importazioni per l'estensione alla sezione delle dipendenze. A causa delle dimensioni dell'estensione ExoPlayer IMA, implementa e attiva il multidex qui. Questo è necessario per le app con minSdkVersion impostato su 20 o meno. Aggiungi anche un nuovo compileOptions per specificare le informazioni sulla compatibilità con la versione Java.

app/build.gradle

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 la richiesta di 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>

Aggiungere dichiarazioni di intenti

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 intenti per aprire i link web. Aggiungi il seguente snippet al file manifest della tua app per attivare i clic sugli annunci (utenti che fanno clic sul pulsante Scopri di più).

Nota: le versioni future dell'SDK IMA includeranno automaticamente queste dichiarazioni e verranno unite al file manifest dell'applicazione.

  <?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. Crea il contenitore dell'interfaccia utente dell'annuncio

Crea la vista da utilizzare come PlayerView di ExoPlayer creando un oggetto StyledPlayerView con un ID appropriato. Cambia anche androidx.constraintlayout.widget.ConstraintLayout in LinearLayout.

app/src/main/res/layout/activity_main.xml

<?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.

app/src/main/res/values/strings.xml

<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 ExoPlayer IMA

Aggiungi le istruzioni di importazione per l'estensione ExoPlayer. Aggiorna poi la classe MainActivity per estendere Activity aggiungendo variabili private per PlayerView, SimpleExoPlayer e ImaAdsLoader.

app/src/main/java/com/example/project name/MainActivity.java

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

Sostituisci il metodo onCreate e aggiungi le assegnazioni di variabili richieste per creare un nuovo oggetto adsLoader con l'URL del tag annuncio.

app/src/main/java/com/example/project name/MainActivity.java

...

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 initialize, crea SimpleExoPlayer. Quindi, crea il AdsMediaSource e impostalo sul player.

app/src/main/java/com/example/project name/MainActivity.java

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 del giocatore

Infine, crea i callback per gli eventi del ciclo di vita del player:

• onStart
• onResume
• onStop
• onPause
• onDestroy

Nota: il codice di esempio utilizza onStart/onStop per le versioni 24 e successive dell'SDK Android e onResume/onPause per le versioni precedenti alla 24.

app/src/main/java/com/example/project name/MainActivity.java

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 altre funzionalità dell'SDK, consulta le altre guide o i sample su GitHub.