IMA SDK memudahkan pengintegrasian iklan multimedia ke dalam situs dan aplikasi Anda. IMA SDK dapat meminta iklan dari server iklan mana pun yang sesuai dengan VAST dan mengelola pemutaran iklan di aplikasi Anda. Dengan SDK sisi klien IMA, Anda mempertahankan kontrol atas pemutaran video konten, sedangkan SDK menangani pemutaran iklan. Iklan diputar di pemutar video terpisah yang diposisikan di atas pemutar video konten aplikasi.
Panduan ini menunjukkan cara mengintegrasikan IMA SDK ke dalam aplikasi pemutar video sederhana. Jika Anda ingin melihat atau mengikuti contoh integrasi yang telah selesai, download contoh sederhana dari GitHub. Jika Anda tertarik dengan pemutar HTML5 dengan SDK praintegrasi, lihat Plugin IMA SDK untuk Video.js.
Ringkasan sisi klien IMA
Mengimplementasikan sisi klien IMA melibatkan empat komponen SDK utama, yang ditunjukkan dalam panduan ini:
AdDisplayContainer
: Objek penampung tempat iklan dirender.AdsLoader
: Objek yang meminta iklan dan menangani peristiwa dari respons permintaan iklan. Anda hanya boleh membuat satu loader iklan, yang dapat digunakan kembali selama masa pakai aplikasi.AdsRequest
: Objek yang menentukan permintaan iklan. Permintaan iklan menentukan URL untuk tag iklan VAST, serta parameter tambahan, seperti dimensi iklan.AdsManager
: Objek yang berisi respons terhadap permintaan iklan, mengontrol pemutaran iklan, dan memproses peristiwa iklan yang diaktifkan oleh SDK.
Prasyarat
Sebelum memulai, Anda akan memerlukan hal berikut:
- Tiga file kosong:
- index.html
- style.css
- ads.js
- Python yang diinstal di komputer Anda, atau server web yang digunakan untuk pengujian
1. Memulai server pengembangan
Karena IMA SDK memuat dependensi melalui protokol yang sama dengan halaman asal pemuatannya, Anda harus menggunakan server web untuk menguji aplikasi Anda. Cara termudah untuk memulai server pengembangan lokal adalah dengan menggunakan server bawaan Python.
- Dengan menggunakan command line, dari direktori yang berisi
file index.html, jalankan:
python -m http.server 8000
- Di browser web, buka
http://localhost:8000/
Anda juga dapat menggunakan server web lain, seperti Apache HTTP Server.
2. Membuat pemutar video sederhana
Pertama, ubah index.html untuk membuat elemen video HTML5 sederhana, yang dimuat dalam elemen penggabungan, dan tombol untuk memicu pemutaran. Tambahkan juga tag yang diperlukan untuk memuat file style.css dan ads.js. Kemudian, ubah styles.css agar pemutar video responsif untuk perangkat seluler. Terakhir, di ads.js, picu pemutaran video saat tombol putar diklik.
index.html<!doctype html> <html lang="en"> <head> <title>IMA HTML5 Simple Demo</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <link rel="stylesheet" href="style.css"> </head> <body> <div id="page-content"> <div id="video-container"> <video id="video-element"> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4"> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm"> </video> </div> <button id="play-button">Play</button> </div> <script src="ads.js"></script> </body> </html>style.css
#page-content { position: relative; /* this element's width controls the effective height */ /* of the video container's padding-bottom */ max-width: 640px; margin: 10px auto; } #video-container { position: relative; /* forces the container to match a 16x9 aspect ratio */ /* replace with 75% for a 4:3 aspect ratio, if needed */ padding-bottom: 56.25%; } #video-element { /* forces the contents to fill the container */ position: absolute; top: 0; left: 0; width: 100%; height: 100%; }ads.js
var videoElement; // On window load, attach an event to the play button click // that triggers playback on the video element window.addEventListener('load', function(event) { videoElement = document.getElementById('video-element'); var playButton = document.getElementById('play-button'); playButton.addEventListener('click', function(event) { videoElement.play(); }); });
Setelah menyelesaikan langkah ini, ketika Anda membuka index.html di browser (melalui server pengembangan), Anda akan dapat melihat elemen video dan video akan dimulai saat Anda mengklik tombol putar.
3. Mengimpor IMA SDK
Selanjutnya, tambahkan framework IMA menggunakan tag skrip di index.html, sebelum tag untuk
ads.js
.
... </video> </div> <button id="play-button">Play</button> </div> <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script> <script src="ads.js"></script> </body> </html>
4. Lampirkan pengendali halaman dan pemutar video
Untuk mengubah perilaku pemutar video dengan JavaScript, tambahkan pengendali peristiwa yang memicu tindakan berikut:
- Setelah halaman selesai dimuat, lakukan inisialisasi IMA SDK.
- Saat tombol putar video diklik, muat iklan (kecuali jika sudah ada iklan yang dimuat).
- Saat jendela browser diubah ukurannya, perbarui elemen video dan dimensi
adsManager
agar halamannya responsif untuk perangkat seluler
var videoElement; // Define a variable to track whether there are ads loaded and initially set it to false var adsLoaded = false; window.addEventListener('load', function(event) { videoElement = document.getElementById('video-element'); initializeIMA(); videoElement.addEventListener('play', function(event) { loadAds(event); }); var playButton = document.getElementById('play-button'); playButton.addEventListener('click', function(event) { videoElement.play(); }); }); window.addEventListener('resize', function(event) { console.log("window resized"); }); function initializeIMA() { console.log("initializing IMA"); } function loadAds(event) { // Prevent this function from running on if there are already ads loaded if(adsLoaded) { return; } adsLoaded = true; // Prevent triggering immediate playback when ads are loading event.preventDefault(); console.log("loading ads"); }
5. Membuat penampung iklan
Di sebagian besar browser, IMA SDK menggunakan elemen penampung iklan khusus untuk menampilkan iklan sekaligus
elemen UI terkait iklan. Penampung ini harus diubah ukurannya agar dapat menempatkan elemen video dari
pojok kiri atas. Tinggi dan lebar iklan yang ditempatkan di penampung ini ditetapkan oleh
objek adsManager
, sehingga Anda tidak perlu menetapkan nilai ini secara manual.
Untuk menerapkan elemen penampung iklan ini, pertama-tama buat div
baru di dalam elemen
video-container
. Kemudian, update CSS untuk memosisikan elemen di sudut kiri
atas video-element
. Terakhir, tentukan variabel untuk penampung dalam
fungsi initializeIMA()
yang berjalan saat halaman dimuat.
... <div id="video-container"> <video id="video-element" controls> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4"> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm"> </video> <div id="ad-container"></div> </div> ...style.css
... #ad-container { position: absolute; top: 0; left: 0; width: 100%; }ads.js
var videoElement; var adsLoaded = false; var adContainer; ... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); }
6. Menginisialisasi AdsLoader dan membuat permintaan iklan
Untuk meminta kumpulan iklan, buat instance ima.AdsLoader
. Instance ini
menggunakan objek AdDisplayContainer
sebagai input dan dapat digunakan untuk memproses
objek ima.AdsRequest
yang terkait dengan URL tag iklan yang ditentukan. Tag iklan yang digunakan dalam contoh ini berisi iklan pre-roll berdurasi 10 detik. Anda dapat menguji URL tag iklan ini atau apa pun menggunakan
IMA Video Suite Inspector.
Sebagai praktik terbaik, hanya pertahankan satu instance ima.AdsLoader
untuk seluruh
siklus proses halaman. Untuk membuat permintaan iklan tambahan, buat objek ima.AdsRequest
baru, tetapi gunakan kembali ima.AdsLoader
yang sama. Untuk informasi selengkapnya, lihat
FAQ IMA SDK.
var videoElement; var adsLoaded = false; var adContainer; var adDisplayContainer; var adsLoader; ... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement); adsLoader = new google.ima.AdsLoader(adDisplayContainer); // Let the AdsLoader know when the video has ended videoElement.addEventListener('ended', function() { adsLoader.contentComplete(); }); var adsRequest = new google.ima.AdsRequest(); adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' + 'iu=/21775744923/external/single_ad_samples&sz=640x480&' + 'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&' + 'gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator='; // Specify the linear and nonlinear slot sizes. This helps the SDK to // select the correct creative if multiple are returned. adsRequest.linearAdSlotWidth = videoElement.clientWidth; adsRequest.linearAdSlotHeight = videoElement.clientHeight; adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth; adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3; // Pass the request to the adsLoader to request ads adsLoader.requestAds(adsRequest); }
7. Memproses peristiwa AdsLoader
Jika iklan berhasil dimuat, ima.AdsLoader
akan memunculkan peristiwa
ADS_MANAGER_LOADED
. Uraikan peristiwa yang diteruskan ke callback untuk menginisialisasi objek AdsManager
. AdsManager
memuat masing-masing iklan seperti yang ditentukan oleh respons terhadap URL tag iklan.
Selain itu, pastikan untuk menangani error yang mungkin terjadi selama proses pemuatan. Jika iklan tidak dimuat, pastikan pemutaran media berlanjut, tanpa iklan, agar tidak mengganggu pengalaman pengguna.
ads.jsvar videoElement; var adsLoaded = false; var adContainer; var adDisplayContainer; var adsLoader; var adsManager; ... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement); adsLoader = new google.ima.AdsLoader(adDisplayContainer); adsLoader.addEventListener( google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED, onAdsManagerLoaded, false); adsLoader.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false); ... function onAdsManagerLoaded(adsManagerLoadedEvent) { // Instantiate the AdsManager from the adsLoader response and pass it the video element adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); } function onAdError(adErrorEvent) { // Handle the error logging. console.log(adErrorEvent.getError()); if(adsManager) { adsManager.destroy(); } }
8. Memulai AdsManager
Untuk memulai pemutaran iklan, Anda harus memulai AdsManager
. Untuk sepenuhnya mendukung browser seluler, hal ini harus dipicu oleh interaksi pengguna.
... function loadAds(event) { // prevent this function from running on every play event if(adsLoaded) { return; } adsLoaded = true; // prevent triggering immediate playback when ads are loading event.preventDefault(); console.log("loading ads"); // Initialize the container. Must be done via a user action on mobile devices. videoElement.load(); adDisplayContainer.initialize(); var width = videoElement.clientWidth; var height = videoElement.clientHeight; try { adsManager.init(width, height, google.ima.ViewMode.NORMAL); adsManager.start(); } catch (adError) { // Play the video without ads, if an error occurs console.log("AdsManager could not be started"); videoElement.play(); } } ...
9. Membuat AdsManager menjadi responsif
Untuk memastikan iklan diubah ukurannya secara dinamis agar sesuai dengan ukuran pemutar video, jika layar berubah ukuran atau orientasi, peristiwa pengubahan ukuran jendela harus memanggil adsManager.resize()
.
... window.addEventListener('resize', function(event) { console.log("window resized"); if(adsManager) { var width = videoElement.clientWidth; var height = videoElement.clientHeight; adsManager.resize(width, height, google.ima.ViewMode.NORMAL); } }); ...
10. Memproses peristiwa AdsManager
AdsManager
juga mengaktifkan beberapa peristiwa yang harus ditangani. Peristiwa ini digunakan untuk melacak perubahan status, memicu pemutaran dan jeda pada video konten, serta mendaftarkan error.
Menangani error
Pengendali error yang dibuat untuk AdsLoader
dapat berfungsi sebagai pengendali error untuk
AdsManager
dengan menambahkan pengendali peristiwa baru dengan fungsi callback yang sama.
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); } ...
Memicu peristiwa putar dan jeda
Saat AdsManager
siap menyisipkan iklan untuk ditampilkan, peristiwa CONTENT_PAUSE_REQUESTED
akan diaktifkan. Tangani peristiwa ini dengan memicu jeda pada
pemutar video yang mendasarinya. Demikian pula, saat iklan selesai, AdsManager
akan mengaktifkan
peristiwa CONTENT_RESUME_REQUESTED
. Tangani peristiwa ini dengan memulai ulang pemutaran di
video konten yang mendasarinya.
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED, onContentResumeRequested); } ... function onContentPauseRequested() { videoElement.pause(); } function onContentResumeRequested() { videoElement.play(); }
Memicu klik untuk menjeda di perangkat seluler
Karena AdContainer
menempatkan elemen video, pengguna tidak dapat berinteraksi langsung dengan
pemutar yang mendasarinya. Hal ini dapat membingungkan pengguna perangkat seluler, yang berharap dapat mengetuk
pemutar video untuk menjeda pemutaran. Untuk mengatasi masalah ini, IMA SDK meneruskan klik apa pun yang tidak
ditangani oleh IMA dari overlay iklan ke elemen AdContainer
, tempat klik tersebut dapat
ditangani. Hal ini tidak berlaku untuk iklan linear di browser non-seluler, karena mengklik iklan akan membuka
link klik-tayang.
Untuk menerapkan klik untuk menjeda, tambahkan pengendali klik ke AdContainer
dan picu peristiwa putar
atau jeda pada video yang mendasarinya.
... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); adContainer.addEventListener('click', adContainerClick); adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement); adsLoader = new google.ima.AdsLoader(adDisplayContainer); ... function adContainerClick(event) { console.log("ad container clicked"); if(videoElement.paused) { videoElement.play(); } else { videoElement.pause(); } } ...
Memicu pemutaran pada iklan non-linear
AdsManager
menjeda video konten saat iklan siap diputar, tetapi perilaku ini tidak memperhitungkan iklan non-linear, yaitu konten akan terus diputar saat iklan ditampilkan. Untuk mendukung iklan non-linear, proses AdsManager
untuk memunculkan
peristiwa LOADED
. Kemudian, periksa apakah iklan tersebut linear, dan jika tidak, lanjutkan pemutaran di elemen video.
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED, onContentResumeRequested); adsManager.addEventListener( google.ima.AdEvent.Type.LOADED, onAdLoaded); } ... function onAdLoaded(adEvent) { var ad = adEvent.getAd(); if (!ad.isLinear()) { videoElement.play(); } }
Selesai. Anda kini meminta dan menampilkan iklan dengan IMA SDK. Untuk mempelajari fitur SDK lanjutan lainnya, lihat panduan lainnya atau contoh di GitHub.