Pemutaran iklan kustom dengan IMA SDK untuk Android

Tidak digunakan lagi: Pemutaran iklan kustom sebelumnya menjelaskan cara mengintegrasikan IMA SDK terpisah dari "pemutaran iklan yang dimiliki SDK". "Pemutaran iklan milik SDK" tidak digunakan lagi dan mendukung Ekstensi ExoPlayer-IMA sebagai cara cepat dan mudah untuk mengintegrasikan IMA SDK untuk Android ke dalam aplikasi Anda. Ekstensi dan SDK menangani semua logika pemutaran iklan, sedangkan aplikasi Anda berfokus pada pemutaran video konten. Tujuan Panduan memulai IMA Android kini mencakup integrasi IMA yang mirip dengan pemutaran iklan kustom, di mana Anda dapat memutar iklan di pemutar video Anda sendiri.

Di IMA v3.30.0 dan versi yang lebih lama, IMA SDK dapat menangani semua logika pemutaran iklan, sementara aplikasi Anda berfokus pada memutar video konten. Pendekatan ini disebut "Pemutaran iklan milik SDK".

Jika Anda ingin memutar iklan di pemutar video, SDK menyediakan antarmuka untuk itu. Kami menyebut pendekatan ini sebagai pemutaran iklan" dan bagian selanjutnya dalam panduan ini akan membahas penerapannya.

Prasyarat

• Integrasi IMA dasar.

Sebaiknya lihat Contoh Lanjutan di github sebagai titik awal jika Anda saat ini tidak memiliki IMA dasar integrasi. Contoh ini sudah menerapkan pemutaran iklan kustom. Sisanya dalam panduan ini akan menjelaskan fitur yang diperlukan untuk pemutaran iklan khusus Iklan IMA.

Poin Penting: Contoh Dasar mengimplementasikan Ekstensi Exoplayer-IMA yang menangani sebagian besar penyiapan IMA SDK. Karena itu, Contoh Dasar tidak dapat digunakan sebagai titik awal untuk panduan ini.

Antarmuka dengan VideoAdPlayer

Pemutaran iklan kustom mengharuskan aplikasi Anda menerapkan VideoAdPlayer dalam antarmuka berbasis web yang sederhana. Antarmuka ini digunakan oleh SDK untuk memberi tahu aplikasi Anda agar memutar iklan video. Aplikasi Anda juga menggunakan antarmuka ini untuk memberi tahu SDK tentang iklan video utama peristiwa. Ikuti langkah-langkah berikut untuk menerapkan antarmuka.

Membuat VideoAdPlayer

Langkah pertama adalah membuat class VideoAdPlayer anonim dalam requestAds():

private VideoAdPlayer videoAdPlayer;
...

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

Tambahkan metode video

Berikutnya, tambahkan metode yang memberi tahu pemutar video untuk memutar, memuat, menghentikan, dan menjeda iklan video. Kami juga menambahkan metode untuk melepaskan pemutar dan mendapatkan volume di sini:

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

Metode ini adalah wrapper tipis di sekitar metode. Perlu diperhatikan bahwa metode ini menetapkan variabel internal yang digunakan untuk melacak apakah iklan ditampilkan. Pada pemutaran iklan kustom, pemutar video memutar video konten dan iklan video, jadi Anda harus yang sedang ditampilkan.

Progres pemutaran iklan

Antarmuka VideoAdPlayer mengimplementasikan antarmuka lain, AdProgressProvider, jadi Anda juga harus menerapkannya. Hanya memiliki satu metode, getAdProgress(), yang digunakan SDK untuk mendapatkan informasi pemutaran untuk iklan. Tambahkan ke VideoAdPlayer anonim Anda , di bawah metode lainnya:

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() menampilkan jenis VideoProgressUpdate, yang harus terdiri dari posisi dan durasi video saat ini. Jika pemain tidak memutar iklan, atau durasi tidak tersedia, minta iklan ditampilkan VideoProgressUpdate.VIDEO_TIME_NOT_READY seperti yang ditunjukkan dalam contoh.

Mengelola callback video

Pemutaran iklan kustom mengharuskan aplikasi Anda memberi tahu SDK tentang peristiwa video. Dari tampilan SDK, ini adalah callback yang yang dijelaskan oleh antarmuka VideoAdPlayer.VideoAdPlayerCallback. Sebelum masuk ke metode callback itu sendiri, Anda harus menambahkan dan menghapus callback atas permintaan SDK. Ini adalah dilakukan di dalam VideoAdPlayer menggunakan addCallback() dan 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);
        }
};

Penerapan ini menggunakan List<> untuk callback yang akan dipanggil metode List<>.add() dan remove().

Memanggil callback

Setelah SDK memiliki cara memberi tahu aplikasi Anda untuk menambahkan dan menghapus callback, menentukan tempat pemanggilan callback. Aplikasi Anda perlu memanggil callback ini saat peristiwa penting terjadi, seperti pemutaran, jeda atau melanjutkan video, atau saat video selesai atau mengalami error.

Untuk melakukannya, luaskan SampleVideoPlayer agar memiliki pemroses untuk ini peristiwa video yang ditambahkan dari VideoFragment. Alasan untuk membuat pemroses terpisah di SampleVideoPlayer untuk memanggil callback iklan ini adalah karena SampleVideoPlayer tidak tahu apa pun tentang iklan, jadi Anda harus meneruskan peristiwa videonya ke sesuatu yang dapat menangani iklan.

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

Memulai, menjeda, dan melanjutkan

Membuat enum baru untuk melacak status pemutaran dan menambahkan penggantian baru untuk metode start() dan pause() di 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();
    }
}

Menangani error

Ganti pemroses error anonim pemutar video yang Anda tetapkan di 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;
}

Mengimplementasikan pemroses

Kembali ke VideoFragment dan tambahkan OnVideoEventsListener anonim ke 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();
            }
        }
    }
});

Mengubah metode onVideoCompleted() dari OnVideoCompletedListener untuk menangani kasus saat video iklan sudah selesai:

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

Beralih antara konten dan iklan

Contoh ini menggunakan instance pemutar video yang sama untuk memutar keduanya konten dan iklan. Oleh karena itu, Anda perlu menambahkan beberapa logika untuk beralih konten dan iklan pada pemutar Anda. Anda kemudian dapat memuat ulang dan mencari video konten untuk kembali ke titik awal iklan. Tambahkan dua fungsi untuk melakukannya:

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

Ini dipanggil saat CONTENT_PAUSE_REQUESTED dan CONTENT_RESUME_REQUESTED peristiwa diterima, dalam VideoFragment.onAdEvent(), masing-masing:

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

Aktifkan pemutaran iklan kustom

Langkah terakhir adalah memberi tahu SDK bahwa Anda menggunakan pemutaran iklan kustom. Hal ini dilakukan dengan meneruskan VideoAdPlayer ke AdDisplayContainer Anda:

adDisplayContainer.setPlayer(videoAdPlayer);

Anda harus meneruskan pemutar ke setPlayer(). Jika tidak, SDK menggunakan pemutaran yang dimiliki SDK.

Selesai. Itulah semua langkah yang diperlukan untuk menambahkan pemutaran iklan kustom ke Penerapan IMA. Anda dapat membandingkan penerapan Anda sendiri dengan Contoh Lanjutan di github jika Anda mengalami masalah.