Pemutaran iklan kustom dengan IMA SDK untuk Android

Cara tercepat dan paling mudah untuk mengintegrasikan IMA SDK untuk Android ke dalam aplikasi Anda adalah dengan membuat SDK menangani semua logika pemutaran iklan, sementara aplikasi Anda berfokus pada pemutaran video konten. Pendekatan ini, yang disebut "pemutaran iklan milik SDK", adalah opsi default dalam Memulai.

Namun, jika Anda juga ingin memutar iklan di pemutar video, SDK menyediakan antarmuka untuk itu. Kami menyebut pendekatan ini sebagai "pemutaran iklan kustom" dan seluruh panduan ini membahas penerapannya.

Prasyarat

• Integrasi IMA dasar.

Sebaiknya lihat Contoh Lanjutan di github sebagai titik awal jika saat ini Anda tidak memiliki integrasi IMA dasar. Contoh ini sudah menerapkan pemutaran iklan kustom. Bagian selanjutnya dari panduan ini akan menjelaskan fitur-fitur yang diperlukan untuk pemutaran iklan kustom dengan iklan IMA.

Poin Penting: Contoh Dasar menerapkan ekstensi Exoplayer-IMA yang menangani sebagian besar penyiapan IMA SDK. Oleh karena itu, Contoh Dasar tidak dapat digunakan sebagai titik awal untuk panduan ini.

Antarmuka dengan VideoAdPlayer

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

Membuat VideoAdPlayer

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

private VideoAdPlayer videoAdPlayer;
...

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

Menambahkan metode video

Selanjutnya, tambahkan metode yang memberi tahu pemutar video untuk memutar, memuat, menghentikan, dan menjeda video iklan. 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 serupa pada pemutar video Anda. Perhatikan bahwa metode ini menetapkan variabel internal yang digunakan untuk melacak apakah iklan ditampilkan atau tidak. Dalam pemutaran iklan kustom, pemutar video memutar iklan video dan video konten, sehingga Anda perlu melacak iklan yang saat ini ditampilkan.

Progres pemutaran iklan

Antarmuka VideoAdPlayer mengimplementasikan antarmuka lain, AdProgressProvider, jadi Anda juga harus menerapkannya. Ini hanya memiliki satu metode, getAdProgress(), yang digunakan oleh SDK untuk mendapatkan informasi pemutaran iklan. Tambahkan ke class 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 pemutar tidak memutar iklan, atau durasi tidak tersedia, minta pemutar menampilkan 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 besar. Dari tampilan SDK, ini adalah callback yang dijelaskan oleh antarmuka VideoAdPlayer.VideoAdPlayerCallback. Sebelum masuk ke metode callback itu sendiri, Anda harus dapat menambahkan dan menghapus callback atas permintaan SDK. Hal ini 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);
        }
};

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

Memanggil callback

Setelah SDK memiliki cara untuk memberi tahu aplikasi Anda agar menambahkan dan menghapus callback, tentukan tempat pemanggilan callback. Aplikasi Anda perlu memanggil callback ini saat peristiwa video besar terjadi, seperti memutar, menjeda, atau melanjutkan video, atau saat video selesai atau mengalami error.

Untuk melakukannya, luaskan SampleVideoPlayer agar memiliki pemroses untuk peristiwa video ini yang ditambahkan dari VideoFragment. Alasan untuk membuat pemroses terpisah di SampleVideoPlayer untuk memanggil callback iklan ini adalah karena SampleVideoPlayer tidak mengetahui 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);
}

Mulai, jeda, dan lanjutkan

Buat 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 Anda:

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

Ubah metode onVideoCompleted() dari OnVideoCompletedListener untuk menangani kasus ketika video iklan 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 konten dan iklan, sehingga Anda perlu menambahkan beberapa logika untuk beralih antara konten dan iklan di pemutar. Kemudian, Anda dapat memuat ulang dan mencari video konten untuk kembali ke titik tempat iklan dimulai. 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;
}

Metode ini dipanggil saat peristiwa CONTENT_PAUSE_REQUESTED dan CONTENT_RESUME_REQUESTED diterima, di VideoFragment.onAdEvent():

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

Mengaktifkan 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 akan menggunakan pemutaran milik SDK.

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