Questa pagina è stata tradotta dall'API Cloud Translation.

Riproduzione di annunci personalizzati con l'SDK IMA per Android

In IMA 3.30.0 e versioni precedenti, l'SDK IMA è in grado di gestire tutta la logica di riproduzione degli annunci, mentre l'app si concentra sulla riproduzione dei contenuti video. Questo approccio è chiamato "Riproduzione dell'annuncio di proprietà dell'SDK".

Se vuoi riprodurre annunci nel video player, l'SDK fornisce un'interfaccia. Questo approccio viene chiamato "personalizzato "Riproduzione dell'annuncio" e il resto di questa guida ne descrive l'implementazione.

Prerequisiti

Un'integrazione IMA di base.

Ti consigliamo di consultare le Esempio avanzato su GitHub come punto di partenza se al momento non disponi di un IMA di base e integrazione. In questo esempio viene già implementata la riproduzione di annunci personalizzati. Il resto di questa guida verranno descritte le funzionalità necessarie per la riproduzione di annunci personalizzati con annunci IMA.

Interfaccia con VideoAdPlayer

La riproduzione di annunci personalizzati richiede che l'app implementi il metodo VideoAdPlayer a riga di comando. Questa interfaccia viene utilizzata dall'SDK per consentire all'app di riprodurre un annuncio video. La tua app utilizza questa interfaccia anche per informare l'SDK degli annunci video principali eventi. Per implementare l'interfaccia, procedi nel seguente modo.

Crea un riproduttore di annunci video

Il primo passaggio consiste nel creare un corso VideoAdPlayer anonimo tra requestAds():

private VideoAdPlayer videoAdPlayer;
...

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

Aggiungi metodi video

Poi, aggiungi metodi che indichino al video player di riprodurre, caricare, interrompere e mettere in pausa l'annuncio video. Aggiungiamo anche i metodi per rilasciare il player e ottenere il volume qui:

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

Questi metodi sono involucri sottili che circondano le parti simili di machine learning. Tieni presente che questi metodi impostano una variabile interna che viene utilizzata per tenere traccia della visualizzazione di un annuncio. Nella riproduzione di un annuncio personalizzato, video player riproduce annunci video e annunci video, quindi devi traccia di cui è attualmente visualizzata.

Avanzamento della riproduzione dell'annuncio

L'interfaccia VideoAdPlayer implementa un'altra interfaccia, AdProgressProvider, quindi devi implementarlo anche. Ha solo un metodo, getAdProgress(), usato dall'SDK per ottenere informazioni sulla riproduzione degli annunci. Aggiungila al tuo VideoAdPlayer anonimo di seguito gli altri metodi:

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() restituisce un tipo VideoProgressUpdate, che deve essere composta dalla posizione e dalla durata correnti del video. Se il player non sta riproducendo un annuncio o la durata non è disponibile, viene restituito VideoProgressUpdate.VIDEO_TIME_NOT_READY come mostrato nell'esempio.

Gestisci i callback video

Per la riproduzione di annunci personalizzati è necessario che l'app comunichi all'SDK i principali eventi video. Dal punto di vista dell'SDK, si tratta di callback descritto dall'interfaccia VideoAdPlayer.VideoAdPlayerCallback. Prima di passare ai metodi di callback, devi essere in grado di aggiungere e rimuovere i callback su richiesta dell'SDK. Questo è operazione completata all'interno di VideoAdPlayer utilizzando addCallback() e 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);
        }
};

Questa implementazione utilizza un List<> per i callback da cui chiamare i metodi List<>.add() e remove().

Chiama i numeri di telefono

Ora che l'SDK dispone di un modo per comunicare alla tua app di aggiungere e rimuovere i callback, definisci le posizioni in cui viene chiamato il callback. La tua app deve chiamare tramite questi callback quando si verificano eventi video importanti, come la riproduzione o la pausa. o la ripresa di un video oppure quando un video termina o si verifica un errore.

A questo scopo, espandi SampleVideoPlayer in modo da avere un listener per questi Eventi video aggiunti da VideoFragment. Il motivo per rendere un ascoltatore separato in SampleVideoPlayer per richiamare questi callback degli annunci è che SampleVideoPlayer non sa nulla sugli annunci, quindi devi inoltrare gli eventi video a qualcosa che possa gestire gli annunci.

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

Avviare, mettere in pausa e riprendere

Crea una nuova enum per tenere traccia dello stato di riproduzione e aggiungere nuovi override per i metodi start() e pause() in 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();
    }
}

Gestire gli errori

Esegui l'override del listener di errori anonimo del video player impostato in 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;
}

Implementazione del listener

Torna a VideoFragment e aggiungi un OnVideoEventsListener anonimo alla tua istanza 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();
            }
        }
    }
});

Cambia il metodo onVideoCompleted() di OnVideoCompletedListener per gestire il caso di completamento di un video pubblicitario:

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

Passare dai contenuti agli annunci e viceversa

Questo esempio utilizza la stessa istanza del video player per riprodurre entrambi contenuti e annunci, quindi devi aggiungere una logica per passare contenuti e annunci nel player. Dopodiché puoi ricaricare e cercare per tornare al punto in cui è iniziato l'annuncio. Aggiungi due funzioni per farlo:

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

Questi vengono chiamati quando CONTENT_PAUSE_REQUESTED e Ricevuti CONTENT_RESUME_REQUESTED eventi, in VideoFragment.onAdEvent(), rispettivamente:

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

Attiva la riproduzione di annunci personalizzati

L'ultimo passaggio consiste nell'indicare all'SDK che stai utilizzando la riproduzione di annunci personalizzati. Per farlo, passa un valore VideoAdPlayer a AdDisplayContainer:

adDisplayContainer.setPlayer(videoAdPlayer);

È necessario passare il giocatore a setPlayer(). In caso contrario, L'SDK utilizza la riproduzione di proprietà dell'SDK.

È tutto. Questi sono tutti i passaggi necessari per aggiungere la riproduzione di annunci personalizzati al tuo implementazione IMA. Puoi confrontare la tua implementazione con Esempio avanzato su github in caso di problemi.