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

Lecture d'annonces personnalisées avec le SDK IMA pour Android

Dans la version 3.30.0 et les versions antérieures, le SDK IMA peut gérer l'ensemble de la logique de lecture des annonces, tandis que votre application est axée sur la lecture de contenus vidéo. Cette approche s'appelle "Lecture des annonces appartenant au SDK".

Si vous souhaitez diffuser des annonces dans votre lecteur vidéo, le SDK fournit une interface pour cela. Nous désignons cette approche sous le terme lecture des annonces" et le reste de ce guide sur son implémentation.

Prérequis

Une intégration IMA de base.

Nous vous recommandons de consulter Exemple avancé sur GitHub comme point de départ si vous ne disposez pas d'un kit IMA de base l'intégration. Cet exemple intègre déjà la lecture d'annonces personnalisées. Les autres les fonctionnalités nécessaires à la lecture d'annonces personnalisées avec les annonces IMA.

Interface avec VideoAdPlayer

La lecture des annonces personnalisées nécessite que votre application implémente la VideoAdPlayer de commande. Cette interface permet au SDK de demander à votre application de lire l'annonce vidéos. Votre application utilise aussi cette interface pour signaler au SDK toute annonce vidéo majeure événements. Pour implémenter l'interface, procédez comme suit :

Créer un VideoAdPlayer

La première étape consiste à créer une classe VideoAdPlayer anonyme. dans requestAds():

private VideoAdPlayer videoAdPlayer;
...

private void requestAds(String adTagUrl) {
    videoAdPlayer = new VideoAdPlayer() {
    };
}

Ajouter des méthodes vidéo

Ajoutez ensuite des méthodes qui indiquent à votre lecteur vidéo de lire, charger, arrêter et mettre en pause l'annonce. vidéos. Nous ajoutons également les méthodes permettant de libérer le lecteur et d'obtenir le volume ici:

videoAdPlayer = new VideoAdPlayer() {
        @Override
        public void playAd() {
            if (mIsAdDisplayed) {
                videoPlayer.resume();
            } else {
                isAdDisplayed = true;
                videoPlayer.play();
            }
        }

        @Override
        public void loadAd(String url) {
            isAdDisplayed = true;
            videoPlayer.setVideoPath(url);
        }
        @Override
        public void stopAd() {
            videoPlayer.stopPlayback();
        }
        @Override
        public void pauseAd() {
            videoPlayer.pause();
        }

        @Override
        public void release() {
            // any clean up that needs to be done
        }

        @Override
        public int getVolume() {
            return videoPlayer.getVolume();
        }
};

Il s'agit de simples wrappers qui englobent les composants similaires de votre lecteur vidéo méthodes. Notez que ces méthodes définissent une variable interne qui est utilisée pour effectuer le suivi de l'affichage d'une annonce. Avec la lecture d'annonces personnalisées, qui lit à la fois les annonces vidéo et celles du réseau de contenu. Vous devez donc maintenir dont le tracé est actuellement affiché.

Progression de la lecture de l'annonce

L'interface VideoAdPlayer implémente une autre interface, AdProgressProvider. Vous devez donc l'implémenter également. Il ne contient une méthode, getAdProgress(), qui est utilisée par le SDK pour obtenir des informations de lecture pour les annonces. Ajoutez-le à votre VideoAdPlayer anonyme , en dessous des autres méthodes:

VideoAdPlayer videoAdPlayer = new VideoAdPlayer() {
        ...
        @Override
        public VideoProgressUpdate getAdProgress() {
            if (!isAdDisplayed || videoPlayer.getDuration() <= 0) {
                return VideoProgressUpdate.VIDEO_TIME_NOT_READY;
            }
            return new VideoProgressUpdate(videoPlayer.getCurrentPosition(),
                    videoPlayer.getDuration());
        }
};

getAdProgress() renvoie un type VideoProgressUpdate, qui doit correspondre à la position et à la durée actuelles de la vidéo. Si le joueur lorsqu'une annonce n'est pas lue ou si la durée n'est pas disponible, demandez-lui de renvoyer VideoProgressUpdate.VIDEO_TIME_NOT_READY, comme illustré dans l'exemple.

Gérer les rappels vidéo

La lecture des annonces personnalisées nécessite que votre application informe le SDK des des événements vidéo. Du point de vue du SDK, il s'agit de rappels décrit par l'interface VideoAdPlayer.VideoAdPlayerCallback. Avant d'aborder les méthodes de rappel, vous devez en mesure d'ajouter et de supprimer les rappels à la demande du SDK. C'est effectué dans VideoAdPlayer à l'aide de addCallback() et removeCallback():

private List<VideoAdPlayerCallback> adCallbacks = new ArrayList<>(1);

VideoAdPlayer videoAdPlayer = new VideoAdPlayer() {
        ...
        @Override
        public void addCallback(VideoAdPlayerCallback videoAdPlayerCallback) {
            adCallbacks.add(videoAdPlayerCallback);
        }

        @Override
        public void removeCallback(VideoAdPlayerCallback videoAdPlayerCallback) {
            adCallbacks.remove(videoAdPlayerCallback);
        }
};

Cette implémentation utilise un List<> pour les rappels sur lesquels appeler les méthodes List<>.add() et remove().

Appeler les rappels

Maintenant que le SDK peut indiquer à votre application d'ajouter et de supprimer des rappels, définir les endroits où le rappel est appelé. Votre application doit appeler ces rappels lorsque des événements vidéo importants se produisent, comme la lecture, la mise en pause une vidéo, la reprise d'une vidéo, l'arrêt d'une vidéo ou la lecture d'une erreur.

Pour ce faire, développez SampleVideoPlayer afin d'avoir un écouteur pour ces événements vidéo ajoutés depuis VideoFragment. La raison de faire que Un écouteur distinct dans SampleVideoPlayer pour appeler ces rappels d'annonce est que SampleVideoPlayer ne s'y connaît pas du tout au sujet des annonces. Vous devez donc transférer ses événements vidéo à un service capable de gérer les annonces.

public interface OnVideoEventsListener {
    void onPlay();
    void onResume();
    void onPause();
    void onError();
}

private final List<OnVideoEventsListener> onVideoEventsListeners = new ArrayList<>(1);

public void addVideoEventsListener(OnVideoEventsListener listener) {
    onVideoEventsListeners.add(listener);
}

Démarrer, mettre en pause et reprendre

Créer une énumération pour suivre l'état de la lecture et ajouter de nouveaux forçages Pour les méthodes start() et pause() dans SampleVideoPlayer:

private enum PlaybackState {
    STOPPED, PAUSED, PLAYING
}

private PlaybackState playbackState = PlaybackState.STOPPED;

@Override
public void start() {
    super.start();
    switch (playbackState) {
        case STOPPED:
            for (OnVideoEventsListener listener : onVideoEventsListeners) {
                listener.onPlay();
            }
            break;
        case PAUSED:
            for (OnVideoEventsListener listener : onVideoEventsListeners) {
                listener.onResume();
            }
            break;
        default:
            // Already playing; do nothing.
            break;
    }
    playbackState = PlaybackState.PLAYING;
}

@Override
public void pause() {
    super.pause();
    playbackState = PlaybackState.PAUSED;
    for (OnVideoEventsListener listener : onVideoEventsListeners) {
        listener.onPause();
    }
}

Gérer les erreurs

Ignorez l'écouteur d'erreurs anonymes du lecteur vidéo que vous avez défini dans init():

@Override
public boolean onError(MediaPlayer mp, int what, int extra) {
    playbackState = PlaybackState.STOPPED;
    for (OnVideoEventsListener listener : onVideoEventsListeners) {
        listener.onError();
    }

    // Returning true signals to MediaPlayer that the error was handled.
    // This  prevents the completion handler from being called.
    return true;
}

Implémenter l'écouteur

Revenez à VideoFragment et ajoutez un OnVideoEventsListener anonyme à votre instance SampleVideoPlayer:

mVideoPlayer.addVideoEventsListener(new OnVideoEventsListener() {
    @Override
    public void onPlay() {
        if (isAdDisplayed) {
            for (VideoAdPlayerCallback callback : adCallbacks) {
                callback.onPlay();
            }
        }
    }

    @Override
    public void onResume() {
        if (isAdDisplayed) {
            for (VideoAdPlayerCallback callback : adCallbacks) {
                callback.onResume();
            }
        }
    }

    @Override
    public void onPause() {
        if (isAdDisplayed) {
            for (VideoAdPlayerCallback callback : adCallbacks) {
                callback.onPause();
            }
        }
    }

    @Override
    public void onError() {
        if (isAdDisplayed) {
            for (VideoAdPlayerCallback callback : adCallbacks) {
                callback.onError();
            }
        }
    }
});

Modifiez la méthode onVideoCompleted() de OnVideoCompletedListener. pour gérer le cas où une vidéo publicitaire est terminée:

public void onVideoCompleted() {
    // Handle completed event for playing post-rolls.
    if (isAdDisplayed) {
        for (VideoAdPlayerCallback callback : adCallbacks) {
            callback.onEnded();
        }
    } else {
        if (adsLoader != null) {
            adsLoader.contentComplete();
    }
}

Basculer entre le contenu et les annonces

Cet exemple utilise la même instance du lecteur vidéo pour lire à la fois le contenu et les annonces. Vous devez donc ajouter une logique du contenu et des annonces dans votre lecteur. Vous pouvez ensuite recharger la page et rechercher pour revenir au point où l'annonce a commencé. Ajouter deux pour effectuer cette opération:

private int savedContentPosition = 0;

private void pauseContent() {
    savedContentPosition = videoPlayer.getCurrentPosition();
    videoPlayer.stopPlayback();
    isAdDisplayed = true;
}

private void resumeContent() {
    videoPlayer.setVideoPath(getString(R.string.content_url));
    videoPlayer.seekTo(mSavedContentPosition);
    videoPlayer.play();
    isAdDisplayed = false;
}

Elles sont appelées lorsque CONTENT_PAUSE_REQUESTED et CONTENT_RESUME_REQUESTED événements sont reçus dans VideoFragment.onAdEvent(), respectivement:

case CONTENT_PAUSE_REQUESTED:
    pauseContent();
    break;
case CONTENT_RESUME_REQUESTED:
    resumeContent();
    break;

Activer la lecture des annonces personnalisées

La dernière étape consiste à indiquer au SDK que vous utilisez la lecture d'annonces personnalisées. Pour ce faire, transmettez un VideoAdPlayer à votre AdDisplayContainer:

adDisplayContainer.setPlayer(videoAdPlayer);

Vous devez transmettre votre lecteur à setPlayer(). Dans le cas contraire, Le SDK utilise la lecture qui lui appartient.

Et voilà ! Vous connaissez maintenant la procédure à suivre pour activer la lecture d'annonces personnalisées implémentation d'IMA. Vous pouvez comparer votre propre implémentation avec Exemple avancé sur GitHub si vous rencontrez un problème.