Cette page a été traduite par l'API Cloud Translation.

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 DAI, 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é, de sorte que vous n'ayez pas à gérer le basculement entre l'annonce et le contenu vidéo dans votre application.

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 de l'insertion dynamique d'annonce IMA implique quatre composants SDK principaux, présentés dans ce guide:

StreamDisplayContainer : objet conteneur situé 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 diffusion peuvent concerner des vidéos à la demande ou des diffusions en direct. Les requêtes spécifient un Content ID, 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.

Conditions préalables

Android Studio
L'exemple d'application Video Player que vous utiliserez pour intégrer le 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 la fonctionnalité d'insertion dynamique d'annonce du SDK IMA pour Android.

Téléchargez l'application exemple de lecteur vidéo, puis décompressez le fichier.
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.
Exécutez une synchronisation Gradle en sélectionnant Tools > Android > Sync Project with Gradle Files (Outils > Android > Synchroniser le projet avec les fichiers Gradle).
Assurez-vous que l'application du joueur se compile et s'exécute sur un appareil Android physique ou un appareil virtuel Android en sélectionnant Run > Run 'app' (Exécuter > Exécuter "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 du SDK IMA. L'application exemple se compose de deux parties principales:

samplevideoplayer/SampleVideoPlayer.java : lecteur HLS simple basé sur ExoPlayer, qui sert de base pour l'intégration de l'insertion dynamique d'annonce IMA.
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é sous app/build.gradle :

repositories {
  google()
  jcenter()
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.2.0'
    implementation 'androidx.browser:browser:1.3.0'
    implementation 'com.google.android.exoplayer:exoplayer:2.19.0'
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.31.0'
}

Point de contrôle:votre application doit se compiler et s'exécuter, mais vous n'avez pas encore ajouté d'éléments d'interface utilisateur ni de code pour demander et afficher des annonces.

Si votre application cible Android 11 (niveau d'API 30) ou une version ultérieure, les versions actuelle et récente du SDK IMA nécessitent une déclaration d'intention explicite pour ouvrir les liens Web. Ajoutez l'extrait de code suivant au fichier manifeste de votre application afin d'activer les clics sur les annonces (utilisateurs cliquant sur le bouton En savoir plus).

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

Intégrer le SDK IMA

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'annonces IMA. Pour ce faire, vous devez d'abord créer un objet AdsLoader, qui servira à 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 {

    // Live stream 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 = "2528370";
    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());
    }
}

Ajoutez une méthode buildStreamRequest() à AdsLoader pour lui permettre de demander un flux avec des annonces. Il peut s'agir d'un flux en direct avec des annonces (défini par défaut) ou d'un flux de vidéo à la demande(VOD) qui lit 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.

Pour utiliser l'insertion dynamique d'annonce, un lecteur doit transmettre les événements ID3 pour les diffusions en direct aux SDK IMA. Dans l'exemple de code suivant, cette opération est effectuée avec 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);
                    }
                }
            });

    // Live stream 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 live stream to a VOD stream.
    // StreamRequest request = sdkFactory.createVodStreamRequest(TEST_CONTENT_SOURCE_ID,
    //        TEST_VIDEO_ID, null, displayContainer);
    return request;
}

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 mettant en œuvre 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;
}

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

Important: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;
}

Ajoutez le code de 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);
    }
}

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);
            }
        });
    }
…
}

Modifiez le fichier de mise en page de l'activité, activity_my.xml, afin d'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 diffusez des annonces vidéo dans votre application Android. Pour optimiser l'implémentation, consultez les guides sur les favoris et Snapback, ainsi que 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. Consultez ce guide et la documentation de l'API pour détecter d'éventuelles incohérences.

Le problème persiste ? N'hésitez pas à nous contacter sur le forum SDK IMA.