Configurare l'SDK IMA per DAI

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 IMA DAI, le app effettuano una richiesta di streaming per l'annuncio e il video dei contenuti, che possono essere VOD o live. L'SDK restituisce quindi uno stream video combinato, in modo da non dover gestire il passaggio tra l'annuncio e il video di contenuti all'interno dell'app.

Seleziona la soluzione DAI che ti interessa

DAI con servizio completo

Questa guida mostra come integrare l'SDK IMA DAI in una semplice app video player. Se vuoi visualizzare o seguire un esempio di integrazione completato, scarica BasicExample da GitHub.

Panoramica di IMA DAI

L'implementazione di IMA DAI prevede quattro componenti principali dell'SDK, come illustrato in questa guida:

  • StreamDisplayContainer: Un oggetto contenitore che si trova sopra l'elemento di riproduzione video e contiene gli elementi dell'interfaccia utente dell'annuncio.
  • AdsLoader: Un oggetto che richiede flussi e gestisce gli eventi attivati dagli oggetti di risposta alla richiesta di flusso. Devi creare un solo caricatore di annunci, che può essere riutilizzato per tutta la durata dell'applicazione.
  • StreamRequest: un oggetto che definisce una richiesta di stream. Le richieste di stream possono riguardare video on demand o live streaming. Le richieste di live streaming specificano una chiave asset, mentre le richieste VOD specificano un ID CMS e un ID video. Entrambi i tipi di richiesta possono includere facoltativamente una chiave API necessaria per accedere agli stream specificati e un codice di rete Google Ad Manager per l'SDK IMA per gestire gli identificatori pubblicità come specificato nelle impostazioni di Google Ad Manager.
  • StreamManager: Un oggetto che gestisce i flussi di inserimento di annunci dinamici e le interazioni con il backend DAI. Lo stream manager gestisce anche i ping di monitoraggio e inoltra gli eventi di stream e annunci al publisher.

Prerequisiti

  • Android Studio
  • App video player di esempio per l'integrazione dell'SDK

Scaricare ed eseguire l'app di esempio del video player

L'app di esempio fornisce un video player funzionante che riproduce video HLS. Utilizzalo come punto di partenza per integrare le funzionalità DAI dell'SDK IMA DAI.

  1. Scarica l'app di esempio del lettore video ed estraila.

  2. Avvia Android Studio e seleziona Apri un progetto Android Studio esistente oppure, se Android Studio è già in esecuzione, seleziona File > Nuovo > Importa progetto. Quindi scegli SampleVideoPlayer/build.gradle.

  3. Esegui una sincronizzazione Gradle selezionando Strumenti > Android > Sincronizza progetto con file Gradle.

  4. Assicurati che l'app del player venga compilata ed eseguita su un dispositivo Android fisico o su un dispositivo virtuale Android utilizzando Esegui > Esegui "app". È normale che lo stream video impieghi alcuni istanti per caricarsi prima della riproduzione.

Esamina il video player di esempio

Il video player di esempio non contiene ancora alcun codice di integrazione dell'SDK IMA DAI. L'app di esempio è costituita da due parti principali:

  1. samplevideoplayer/SampleVideoPlayer.java: un player HLS basato su ExoPlayer che funge da base per l'integrazione di IMA DAI.

  2. videoplayerapp/MyActivity.java: questa attività crea il video player e gli passa un Context e un media3.ui.PlayerView.

Aggiungere l'SDK IMA DAI all'app del player

Devi includere anche un riferimento all'SDK IMA DAI. In Android Studio, aggiungi quanto segue al file build.gradle a livello di applicazione, che si trova in app/build.gradle. L'SDK IMA richiede l'attivazione della rimozione dello zucchero della libreria, che devi eseguire impostando coreLibraryDesugaringEnabled true e aggiungendo coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5' come dipendenza nel file build.gradle. Per maggiori dettagli, vedi API Java 11+ disponibili tramite desugaring con la specifica nio.

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.5.1"
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
    implementation 'androidx.appcompat:appcompat:1.7.0'
    implementation "androidx.media3:media3-ui:$media3_version"
    implementation "androidx.media3:media3-exoplayer:$media3_version"
    implementation "androidx.media3:media3-exoplayer-hls:$media3_version"
    implementation "androidx.media3:media3-exoplayer-dash:$media3_version"
    implementation 'androidx.mediarouter:mediarouter:1.7.0'
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.36.0'

Integrare l'SDK IMA DAI

  1. Crea una nuova classe denominata SampleAdsWrapper nel pacchetto videoplayerapp (in app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) per includere SampleVideoPlayer esistente e aggiungere la logica di implementazione di IMA DAI. Per farlo, devi prima creare un AdsLoader che viene utilizzato per richiedere lo stream DAI.

    Questo snippet include parametri di esempio per HLS e DASH, stream live e VOD. Per impostare lo stream in riproduzione, aggiorna la variabile CONTENT_TYPE.

    package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
    
    import android.annotation.SuppressLint;
    import android.content.Context;
    import android.view.ViewGroup;
    import android.webkit.WebView;
    import androidx.annotation.Nullable;
    import com.google.ads.interactivemedia.v3.api.AdErrorEvent;
    import com.google.ads.interactivemedia.v3.api.AdEvent;
    import com.google.ads.interactivemedia.v3.api.AdsLoader;
    import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent;
    import com.google.ads.interactivemedia.v3.api.CuePoint;
    import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
    import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer;
    import com.google.ads.interactivemedia.v3.api.StreamManager;
    import com.google.ads.interactivemedia.v3.api.StreamRequest;
    import com.google.ads.interactivemedia.v3.api.StreamRequest.StreamFormat;
    import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
    import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
    import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
    import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer.SampleVideoPlayerCallback;
    import java.util.ArrayList;
    import java.util.HashMap;
    import java.util.List;
    
    /** This class adds ad-serving support to Sample HlsVideoPlayer */
    @SuppressLint("UnsafeOptInUsageError")
    /* @SuppressLint is needed for new media3 APIs. */
    public class SampleAdsWrapper
        implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {
    
      // Live HLS stream asset key.
      private static final String TEST_HLS_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
    
      // Live DASH stream asset key.
      private static final String TEST_DASH_ASSET_KEY = "PSzZMzAkSXCmlJOWDmRj8Q";
    
      // VOD HLS content source and video IDs.
      private static final String TEST_HLS_CONTENT_SOURCE_ID = "2548831";
      private static final String TEST_HLS_VIDEO_ID = "tears-of-steel";
    
      // VOD DASH content source and video IDs.
      private static final String TEST_DASH_CONTENT_SOURCE_ID = "2559737";
      private static final String TEST_DASH_VIDEO_ID = "tos-dash";
    
      private static final String NETWORK_CODE = "21775744923";
    
      private static final String PLAYER_TYPE = "DAISamplePlayer";
    
      private enum ContentType {
        LIVE_HLS,
        LIVE_DASH,
        VOD_HLS,
        VOD_DASH,
      }
    
      // Set CONTENT_TYPE to the associated enum for the stream type you would like to test.
      private static final ContentType CONTENT_TYPE = ContentType.VOD_HLS;
    
      /** Log interface, so we can output the log commands to the UI or similar. */
      public interface Logger {
        void log(String logMessage);
      }
    
      private final ImaSdkFactory sdkFactory;
      private AdsLoader adsLoader;
      private StreamManager streamManager;
      private final List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;
    
      private final SampleVideoPlayer videoPlayer;
      private final Context context;
      private final ViewGroup adUiContainer;
    
      private String fallbackUrl;
      private Logger logger;
    
      /**
       * Creates a new SampleAdsWrapper that implements IMA direct-ad-insertion.
       *
       * @param context the app's context.
       * @param videoPlayer underlying HLS video player.
       * @param adUiContainer ViewGroup in which to display the ad's UI.
       */
      public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) {
        this.videoPlayer = videoPlayer;
        this.context = context;
        this.adUiContainer = adUiContainer;
        sdkFactory = ImaSdkFactory.getInstance();
        playerCallbacks = new ArrayList<>();
        createAdsLoader();
      }
    
      private void enableWebViewDebugging() {
        WebView.setWebContentsDebuggingEnabled(true);
      }
    
      private void createAdsLoader() {
        enableWebViewDebugging();
        VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
        StreamDisplayContainer displayContainer =
            ImaSdkFactory.createStreamDisplayContainer(adUiContainer, videoStreamPlayer);
        videoPlayer.setSampleVideoPlayerCallback(createSampleVideoPlayerCallback());
        adsLoader =
            sdkFactory.createAdsLoader(context, MyActivity.getImaSdkSettings(), displayContainer);
      }
    
      public void requestAndPlayAds() {
        adsLoader.addAdErrorListener(this);
        adsLoader.addAdsLoadedListener(this);
        adsLoader.requestStream(buildStreamRequest());
      }
    
  2. Crea un metodo helper createSampleVideoPlayerCallback() per gestire la creazione di un'istanza di interfaccia SampleVideoPlayerCallback che estende VideoStreamPlayer.VideoStreamPlayerCallback.

    Per funzionare con DAI, il player deve trasmettere gli eventi ID3 per gli stream live all'SDK IMA DAI. Il metodo callback.onUserTextReceived() esegue questa operazione nel seguente codice campione.

    private SampleVideoPlayerCallback createSampleVideoPlayerCallback() {
      return new SampleVideoPlayerCallback() {
        @Override
        public void onUserTextReceived(String userText) {
          for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
            callback.onUserTextReceived(userText);
          }
        }
    
        @Override
        public void onSeek(int windowIndex, long positionMs) {
          // See if we would seek past an ad, and if so, jump back to it.
          long newSeekPositionMs = positionMs;
          if (streamManager != null) {
            CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTimeMs(positionMs);
            if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
              newSeekPositionMs = prevCuePoint.getStartTimeMs();
            }
          }
          videoPlayer.seekTo(windowIndex, newSeekPositionMs);
        }
    
        @Override
        public void onContentComplete() {
          for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
            callback.onContentComplete();
          }
        }
    
        @Override
        public void onPause() {
          for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
            callback.onPause();
          }
        }
    
        @Override
        public void onResume() {
          for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
            callback.onResume();
          }
        }
    
        @Override
        public void onVolumeChanged(int percentage) {
          for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
            callback.onVolumeChanged(percentage);
          }
        }
      };
    }
    
  3. Aggiungi un metodo buildStreamRequest() per creare SteamRequest. Questo metodo passa da un flusso all'altro in base a come imposti la variabile CONTENT_TYPE. Lo stream predefinito utilizzato in questa guida è lo stream HLS VOD di esempio di IMA.

    @Nullable
    private StreamRequest buildStreamRequest() {
      StreamRequest request;
      switch (CONTENT_TYPE) {
        case LIVE_HLS:
          // Live HLS stream request.
          return sdkFactory.createLiveStreamRequest(TEST_HLS_ASSET_KEY, null, NETWORK_CODE);
        case LIVE_DASH:
          // Live DASH stream request.
          return sdkFactory.createLiveStreamRequest(TEST_DASH_ASSET_KEY, null, NETWORK_CODE);
        case VOD_HLS:
          // VOD HLS request.
          request =
              sdkFactory.createVodStreamRequest(
                  TEST_HLS_CONTENT_SOURCE_ID, TEST_HLS_VIDEO_ID, null, NETWORK_CODE);
          request.setFormat(StreamFormat.HLS);
          return request;
        case VOD_DASH:
          // VOD DASH request.
          request =
              sdkFactory.createVodStreamRequest(
                  TEST_DASH_CONTENT_SOURCE_ID, TEST_DASH_VIDEO_ID, null, NETWORK_CODE);
          request.setFormat(StreamFormat.DASH);
          return request;
      }
      // Content type not selected.
      return null;
    }
    
  4. Per riprodurre lo stream, devi anche avere un VideoStreamPlayer, quindi aggiungi un metodo createVideoStreamPlayer(), che crea una classe anonima che implementa VideoStreamPlayer.

    private VideoStreamPlayer createVideoStreamPlayer() {
      return new VideoStreamPlayer() {
        @Override
        public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
          videoPlayer.setStreamUrl(url);
          videoPlayer.play();
        }
    
        @Override
        public void pause() {
          // Pause player.
          videoPlayer.pause();
        }
    
        @Override
        public void resume() {
          // Resume player.
          videoPlayer.play();
        }
    
        @Override
        public int getVolume() {
          // Make the video player play at the current device volume.
          return 100;
        }
    
        @Override
        public void addCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
          playerCallbacks.add(videoStreamPlayerCallback);
        }
    
        @Override
        public void removeCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
          playerCallbacks.remove(videoStreamPlayerCallback);
        }
    
        @Override
        public void onAdBreakStarted() {
          // Disable player controls.
          videoPlayer.enableControls(false);
          log("Ad Break Started\n");
        }
    
        @Override
        public void onAdBreakEnded() {
          // Re-enable player controls.
          if (videoPlayer != null) {
            videoPlayer.enableControls(true);
          }
          log("Ad Break Ended\n");
        }
    
        @Override
        public void onAdPeriodStarted() {
          log("Ad Period Started\n");
        }
    
        @Override
        public void onAdPeriodEnded() {
          log("Ad Period Ended\n");
        }
    
        @Override
        public void seek(long timeMs) {
          // An ad was skipped. Skip to the content time.
          videoPlayer.seekTo(timeMs);
          log("seek");
        }
    
        @Override
        public VideoProgressUpdate getContentProgress() {
          return new VideoProgressUpdate(
              videoPlayer.getCurrentPositionMs(), videoPlayer.getDuration());
        }
      };
    }
    
  5. Implementa i listener richiesti e aggiungi il supporto per la gestione degli errori.

    Tieni presente l'implementazione di AdErrorListener, in quanto chiama un URL di riserva se la riproduzione degli annunci non va a buon fine. Poiché i contenuti e gli annunci si trovano in un unico stream, devi essere pronto a chiamare uno stream di riserva se lo stream DAI riscontra un errore.

    /** AdErrorListener implementation */
    @Override
    public void onAdError(AdErrorEvent event) {
      log(String.format("Error: %s\n", event.getError().getMessage()));
      // play fallback URL.
      log("Playing fallback Url\n");
      videoPlayer.setStreamUrl(fallbackUrl);
      videoPlayer.enableControls(true);
      videoPlayer.play();
    }
    
    /** AdEventListener implementation */
    @Override
    public void onAdEvent(AdEvent event) {
      switch (event.getType()) {
        case AD_PROGRESS:
          // Do nothing or else log will be filled by these messages.
          break;
        default:
          log(String.format("Event: %s\n", event.getType()));
          break;
      }
    }
    
    /** AdsLoadedListener implementation */
    @Override
    public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
      streamManager = event.getStreamManager();
      streamManager.addAdErrorListener(this);
      streamManager.addAdEventListener(this);
      streamManager.init();
    }
    
    /** Sets fallback URL in case ads stream fails. */
    void setFallbackUrl(String url) {
      fallbackUrl = url;
    }
    
  6. Aggiungi il codice per la registrazione.

    /** Sets logger for displaying events to screen. Optional. */
    void setLogger(Logger logger) {
      this.logger = logger;
    }
    
    private void log(String message) {
      if (logger != null) {
        logger.log(message);
      }
    }
  7. Modifica MyActivity in videoplayerapp per creare un'istanza e chiamare SampleAdsWrapper. Inoltre, chiama ImaSdkFactory.initialize() qui utilizzando un metodo helper per creare un'istanza ImaSdkSettings.

    package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
    
    import android.annotation.SuppressLint;
    import android.app.Activity;
    import android.content.res.Configuration;
    import android.os.Bundle;
    import android.util.Log;
    import android.view.View;
    import android.widget.ImageButton;
    import android.widget.ScrollView;
    import android.widget.TextView;
    import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
    import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
    import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
    
    /** Main Activity that plays media using {@link SampleVideoPlayer}. */
    @SuppressLint("UnsafeOptInUsageError")
    /* @SuppressLint is needed for new media3 APIs. */
    public class MyActivity extends Activity {
    
      private static final String DEFAULT_STREAM_URL =
          "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
      private static final String APP_LOG_TAG = "ImaDaiExample";
      private static final String PLAYER_TYPE = "DAISamplePlayer";
      private static ImaSdkSettings imaSdkSettings;
    
      protected SampleVideoPlayer sampleVideoPlayer;
      protected ImageButton playButton;
    
      private boolean contentHasStarted = false;
    
      @Override
      protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_my);
    
        // Initialize the IMA SDK as early as possible when the app starts. If your app already
        // overrides Application.onCreate(), call this method inside the onCreate() method.
        // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
        ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());
    
        View rootView = findViewById(R.id.videoLayout);
        sampleVideoPlayer =
            new SampleVideoPlayer(rootView.getContext(), rootView.findViewById(R.id.playerView));
        sampleVideoPlayer.enableControls(false);
        playButton = rootView.findViewById(R.id.playButton);
        final SampleAdsWrapper sampleAdsWrapper =
            new SampleAdsWrapper(this, sampleVideoPlayer, rootView.findViewById(R.id.adUiContainer));
        sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);
    
        final ScrollView scrollView = findViewById(R.id.logScroll);
        final TextView textView = findViewById(R.id.logText);
    
        sampleAdsWrapper.setLogger(
            logMessage -> {
              Log.i(APP_LOG_TAG, logMessage);
              if (textView != null) {
                textView.append(logMessage);
              }
              if (scrollView != null) {
                scrollView.post(() -> scrollView.fullScroll(View.FOCUS_DOWN));
              }
            });
    
        // Set up play button listener to play video then hide play button.
        playButton.setOnClickListener(
            view -> {
              if (contentHasStarted) {
                sampleVideoPlayer.play();
              } else {
                contentHasStarted = true;
                sampleVideoPlayer.enableControls(true);
                sampleAdsWrapper.requestAndPlayAds();
              }
              playButton.setVisibility(View.GONE);
            });
        orientVideoDescription(getResources().getConfiguration().orientation);
      }
    
  8. Aggiungi il metodo helper getImaSdkSettings() per creare un'istanza ImaSdkSettings.

    public static ImaSdkSettings getImaSdkSettings() {
      if (imaSdkSettings == null) {
        imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
        imaSdkSettings.setPlayerType(PLAYER_TYPE);
        // Set any additional IMA SDK settings here.
      }
      return imaSdkSettings;
    }
  9. Modifica il file di layout dell'attività activity_my.xml per aggiungere elementi UI per la registrazione.

    <!-- UI element for viewing SDK event log -->
    <ScrollView
        android:id="@+id/logScroll"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_weight="0.5"
        android:padding="5dp"
        android:background="#DDDDDD">
    
        <TextView
            android:id="@+id/logText"
            android:layout_width="match_parent"
            android:layout_height="wrap_content">
        </TextView>
    </ScrollView>

Complimenti! Ora stai richiedendo e visualizzando annunci video nella tua app per Android. Per perfezionare l'implementazione, consulta Segnalibri, Snapback e la documentazione dell'API.

Risoluzione dei problemi

Se riscontri problemi con la riproduzione di un annuncio video, prova a scaricare il file BasicExample completato. Se funziona correttamente in BasicExample, è probabile che ci sia un problema con il codice di integrazione IMA dell'app.

Se i problemi persistono, visita il forum dell'SDK IMA.