Inizia a utilizzare l'estensione IMA Exoplayer

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.

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

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.

di Gemini Advanced.

Nota. Poiché l'estensione IMA di ExoPlayer include l'SDK IMA in questa guida, sia AdsRequest che AdsManager vengono utilizzati, ma non sono esplicitamente chiamato.

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:

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 per il linguaggio.
   Nota: l'SDK IMA è compatibile con Kotlin. Tuttavia, l'esempio trattato in questa guida utilizza Java.
6. 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.

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 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ù ).

Nota: le versioni future dell'SDK IMA includeranno automaticamente queste dichiarazioni e verranno uniti al file manifest della tua 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. 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.

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

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

Sovrascrivi 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. Nella barra di inizializzazione crea l'SimpleExoPlayer. Poi, crea l'AdsMediaSource e lo imposti 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 dei giocatori

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

• onStart
• onResume
• onStop
• onPause
• onDestroy

di Gemini Advanced.

Nota: Il codice di esempio utilizza l'SDK onStart/onStop per Android versioni 24 e successive 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 stai richiedendo e mostrando gli annunci con l'SDK IMA. Per saperne di più funzioni dell'SDK, consulta le altre guide o su GitHub.