Premiers pas avec le SDK IMA DAI

Les SDK IMA facilitent l'intégration d'annonces multimédias dans vos sites Web et applications. Les SDK IMA peuvent demander des annonces à n'importe quel ad server compatible avec VAST et gérer la lecture des annonces dans vos applications. Avec les SDK IMA pour l'insertion dynamique d'annonce, les applications envoient une demande de flux pour l'annonce et le contenu vidéo (VOD ou contenu en direct). Le SDK renvoie ensuite un flux vidéo combiné, ce qui vous évite d'avoir à gérer le basculement entre les annonces et les vidéos de contenu dans votre application.

Sélectionnez la solution d'insertion dynamique d'annonce qui vous intéresse.

Insertion dynamique d'annonces avec service complet

Ce guide explique comment intégrer le SDK IMA dans une application de lecteur vidéo simple. Si vous souhaitez afficher ou suivre un exemple d'intégration terminé, téléchargez l'exemple BasicExample sur GitHub.

Présentation de l'insertion dynamique d'annonces IMA

L'implémentation d'IMA DAI implique quatre composants SDK principaux, comme expliqué dans ce guide:

  • StreamDisplayContainer : objet conteneur qui se trouve au-dessus de l'élément de lecture vidéo et qui héberge les éléments d'interface utilisateur de l'annonce.
  • AdsLoader : objet qui demande des flux et gère les événements déclenchés par des objets de réponse à une requête de flux. Vous ne devez instancier qu'un seul chargeur d'annonces, que vous pourrez réutiliser pendant toute la durée de vie de l'application.
  • StreamRequest : objet qui définit une requête de flux. Les requêtes de flux peuvent concerner les vidéos à la demande ou les diffusions en direct. Les requêtes spécifient un Content ID, ainsi qu'une clé API ou un jeton d'authentification, ainsi que d'autres paramètres.
  • StreamManager : objet qui gère les flux d'insertion dynamique d'annonce et les interactions avec le backend d'insertion dynamique d'annonce. Il gère également les pings de suivi et transmet les événements de flux et d'annonce à l'éditeur.

Prérequis

  • Android Studio
  • Exemple d'application de lecteur vidéo pour l'intégration du SDK

Télécharger et exécuter l'exemple d'application de lecteur vidéo

L'application exemple fournit un lecteur vidéo fonctionnel qui lit une vidéo HLS. Utilisez-le comme point de départ pour intégrer les fonctionnalités d'insertion dynamique d'annonce du SDK IMA pour Android.

  1. Téléchargez l'exemple d'application de lecteur vidéo et extrayez-le.

  2. Lancez Android Studio, puis sélectionnez Open an existing Android Studio project (Ouvrir un projet Android Studio existant). Si Android Studio est déjà en cours d'exécution, sélectionnez File > New > Import Project (Fichier > Nouveau > Importer un projet). Ensuite, sélectionnez SampleVideoPlayer/build.gradle.

  3. Exécutez une synchronisation Gradle en sélectionnant Tools > Android > Sync Project with Gradle Files (Outils > Android > Synchroniser le projet avec les fichiers Gradle).

  4. Assurez-vous que l'application du lecteur se compile et s'exécute sur un appareil Android physique ou un appareil virtuel Android en accédant à Run > Run 'app' (Exécuter > Exécuter l'application). Il est normal que le flux vidéo mette quelques instants à se charger avant la lecture.

Examiner l'exemple de lecteur vidéo

L'exemple de lecteur vidéo ne contient pas encore de code d'intégration pour le SDK IMA. L'application exemple se compose de deux parties principales:

  1. samplevideoplayer/SampleVideoPlayer.java: lecteur HLS basé sur ExoPlayer et qui sert de base à l'intégration de l'insertion dynamique d'annonce IMA.

  2. videoplayerapp/MyActivity.java: cette activité crée le lecteur vidéo, et lui transmet des éléments Context et SimpleExoPlayerView.

Ajouter le SDK IMA pour Android à l'application de lecture

Vous devez également inclure une référence au SDK IMA. Dans Android Studio, ajoutez le code suivant à votre fichier build.gradle au niveau de l'application, situé dans app/build.gradle:

repositories {
  google()
  mavenCentral()
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'androidx.media3:media3-exoplayer:1.3.1'
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.33.0'
}

Intégrer le SDK IMA

  1. Créez une classe appelée SampleAdsWrapper dans le package videoplayerapp (dans app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) pour encapsuler le SampleVideoPlayer existant et ajouter une logique mettant en œuvre l'insertion dynamique d'annonce IMA. Pour ce faire, vous devez d'abord créer un AdsLoader utilisé pour demander des annonces aux ad servers.

    videoplayerapp/SampleAdsWrapper.java
    package com.google.ads.interactivemedia.v3.samples.videoplayerapp;

import android.annotation.TargetApi;
import android.content.Context;
import android.os.Build;
import android.view.ViewGroup;
import android.webkit.WebView;

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.ImaSdkSettings;
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.player.VideoProgressUpdate;
import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

public class SampleAdsWrapper implements AdEvent.AdEventListener,
        AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {

    // Livestream asset key.
    private static final String TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

    // VOD content source and video IDs.
    private static final String TEST_CONTENT_SOURCE_ID = "2548831";
    private static final String TEST_VIDEO_ID = "tears-of-steel";

    private static final String PLAYER_TYPE = "DAISamplePlayer";

    /**
     * Log interface, so you can output the log commands to the UI or similar.
     */
    public interface Logger {
        void log(String logMessage);
    }

    private ImaSdkFactory sdkFactory;
    private AdsLoader adsLoader;
    private StreamDisplayContainer displayContainer;
    private StreamManager streamManager;
    private List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;

    private SampleVideoPlayer videoPlayer;
    private Context context;
    private ViewGroup adUiContainer;

    private String fallbackUrl;
    private Logger logger;

    public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer,
                            ViewGroup adUiContainer) {
        this.videoPlayer = videoPlayer;
        this.context = context;
        this.adUiContainer = adUiContainer;
        sdkFactory = ImaSdkFactory.getInstance();
        playerCallbacks = new ArrayList<>();
        createAdsLoader();
        displayContainer = sdkFactory.createStreamDisplayContainer(
            this.adUiContainer,
            videoStreamPlayer
        );
    }

    private void createAdsLoader() {
        ImaSdkSettings settings = new ImaSdkSettings();
        adsLoader = sdkFactory.createAdsLoader(context);
    }

    public void requestAndPlayAds() {
        adsLoader.addAdErrorListener(this);
        adsLoader.addAdsLoadedListener(this);
        adsLoader.requestStream(buildStreamRequest());
    }
}

  2. Ajoutez une méthode buildStreamRequest() à AdsLoader afin qu'elle puisse demander un flux avec des annonces. Il s'agit d'une diffusion en direct avec des annonces (définie par défaut) ou d'un flux de vidéo à la demande(VOD) qui diffuse du contenu préenregistré avec des annonces. Pour activer le flux de vidéo à la demande, mettez en commentaire la demande de diffusion en direct et annulez la mise en commentaire de la demande.

    Pour utiliser l'insertion dynamique d'annonce, un lecteur doit transmettre aux SDK IMA les événements ID3 pour les diffusions en direct. Dans l'exemple de code suivant, cette opération est effectuée par la méthode callback.onUserTextReceived().

    videoplayerapp/SampleAdsWrapper.java
    private StreamRequest buildStreamRequest() {
    VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
    videoPlayer.setSampleVideoPlayerCallback(
            new SampleVideoPlayer.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 you would seek past an ad, and if so, jump back to it.
                    long newSeekPositionMs = positionMs;
                    if (streamManager != null) {
                        CuePoint prevCuePoint  =
                                streamManager.getPreviousCuePointForStreamTime(positionMs / 1000);
                        if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
                            newSeekPositionMs = (long) (prevCuePoint.getStartTime() * 1000);
                        }
                    }
                    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);
                    }
                }
            });

    // Livestream request.
    StreamRequest request = sdkFactory.createLiveStreamRequest(
            TEST_ASSET_KEY, null, displayContainer);

    // VOD request. Comment the createLiveStreamRequest() line above and uncomment this
    // createVodStreamRequest() below to switch from a livestream to a VOD stream.
    // StreamRequest request = sdkFactory.createVodStreamRequest(TEST_CONTENT_SOURCE_ID,
    //        TEST_VIDEO_ID, null, displayContainer);
    return request;
}

  3. Vous avez également besoin d'un VideoStreamPlayer pour lire le flux. Vous devez donc ajouter une méthode createVideoStreamPlayer(), qui crée une classe anonyme qui implémente VideoStreamPlayer.

    videoplayerapp/SampleAdsWrapper.java
    private VideoStreamPlayer createVideoStreamPlayer() {
    VideoStreamPlayer player = new VideoStreamPlayer() {
        @Override
        public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
            videoPlayer.setStreamUrl(url);
            videoPlayer.play();
        }

        @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.
            videoPlayer.enableControls(true);
            log("Ad Break Ended\n");
        }

        @Override
        public VideoProgressUpdate getContentProgress() {
            return new VideoProgressUpdate(videoPlayer.getCurrentPosition(),
                    videoPlayer.getDuration());
        }
    };
    return player;
}

  4. Implémentez les écouteurs requis et ajoutez la prise en charge de la gestion des erreurs.

    Notez l'implémentation de AdErrorListener, car elle appelle une URL de remplacement si la lecture des annonces échoue. Étant donné que le contenu et les annonces se trouvent dans un seul flux, vous devez être prêt à appeler un flux de remplacement si le flux d'insertion dynamique d'annonce rencontre une erreur.

    videoplayerapp/SampleAdsWrapper.java
    /** AdErrorListener implementation **/
@Override
public void onAdError(AdErrorEvent event) {
    // play fallback URL.
    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 are 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;
}

  5. Ajoutez du code pour la journalisation.

    videoplayerapp/SampleAdsWrapper.java
    /** 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);
    }
}

  6. Modifiez MyActivity dans videoplayerapp pour instancier et appeler SampleAdsWrapper.

    videoplayerapp/MyActivity.java
    import android.view.ViewGroup;
import android.widget.ScrollView;
...
public class MyActivity extends AppCompatActivity {
...
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_my);
        View rootView = findViewById(R.id.videoLayout);
        videoPlayer = new SampleVideoPlayer(rootView.getContext(),
                (SimpleExoPlayerView) rootView.findViewById(R.id.playerView));
        videoPlayer.enableControls(false);

        final SampleAdsWrapper sampleAdsWrapper = new SampleAdsWrapper(this, videoPlayer,
            (ViewGroup) rootView.findViewById(R.id.adUiContainer));
        sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);

        final ScrollView scrollView = (ScrollView) findViewById(R.id.logScroll);
        final TextView textView = (TextView) findViewById(R.id.logText);

        sampleAdsWrapper.setLogger(new SampleAdsWrapper.Logger() {
            @Override
            public void log(String logMessage) {
                Log.i(APP_LOG_TAG, logMessage);
                if (textView != null) {
                    textView.append(logMessage);
                }
                if (scrollView != null) {
                    scrollView.post(new Runnable() {
                        @Override
                        public void run() {
                            scrollView.fullScroll(View.FOCUS_DOWN);
                        }
                    });
                }
            }
        });

        playButton = (ImageButton) rootView.findViewById(R.id.playButton);
        // Set up play button listener to play video then hide play button.
        playButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                sampleAdsWrapper.requestAndPlayAds();
                playButton.setVisibility(View.GONE);
            }
        });
    }
...
}

  7. Modifiez le fichier de mise en page de l'activité activity_my.xml pour ajouter des éléments d'interface utilisateur pour la journalisation.

    res/layout/activity_my.xml
    ...
    <TextView
        android:id="@+id/playerDescription"
        android:text="@string/video_description"
        android:textAlignment="center"
        android:gravity="center_horizontal"
        android:layout_width="match_parent"
        android:layout_height="0dp"
        android:layout_weight="0.1"
        android:textSize="@dimen/font_size" />
    <!-- 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>
...

Félicitations ! Vous demandez et affichez maintenant des annonces vidéo dans votre application Android. Pour affiner votre implémentation, consultez Favoris, Snapback et la documentation de l'API.

Dépannage

Si vous rencontrez des problèmes lors de la lecture d'une annonce vidéo, essayez de télécharger l'exemple BasicExample terminé. Si elle fonctionne correctement dans BasicExample, il y a probablement un problème avec le code d'intégration IMA de votre application.

Si vous rencontrez toujours des problèmes, consultez le forum sur le SDK IMA.