Ad Placement API didesain untuk mendukung developer AdSense dan AdMob menggunakan iklan interstisial dan reward dalam game HTML5 di web atau dalam aplikasi. Contoh ini menunjukkan cara mengintegrasikan Ad Placement API ke dalam game dan menggunakannya untuk menempatkan iklan interstisial.
Prasyarat
Sebelum memulai, Anda akan memerlukan hal berikut:
- Buat dua file kosong di direktori yang sama:
- index.html
- game.js
- Menginstal Python secara lokal, atau menggunakan server web untuk menguji implementasi Anda
Kode contoh aplikasi
Penayang AdMob dapat mendownload contoh kode aplikasi untuk lebih memahami cara API dapat diintegrasikan ke dalam game aplikasi.
1. Memulai server pengembangan
Karena Ads Placement API memuat dependensi melalui protokol yang sama dengan halaman tempat aplikasi dimuat, Anda perlu menggunakan server web untuk menguji aplikasi. Anda dapat menggunakan server bawaan Python untuk membuat lingkungan pengembangan lokal.
Buka terminal.
Buka direktori yang berisi file index.html, lalu jalankan:
python -m http.server 8000
Di browser web, buka
localhost:8000
Anda juga dapat menggunakan server web lainnya, seperti Apache HTTP Server.
2. Membuat game HTML5
Ubah index.html
untuk membuat elemen kanvas HTML5 dan tombol untuk memicu gameplay. Kemudian, tambahkan tag skrip yang diperlukan untuk memuat file game.js
.
index.html
<!doctype html>
<html lang="en">
<head>
<title>Ad Placement API HTML5 demo</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<canvas id="gameContainer" height="300px" width="300px"></canvas>
<button id="playButton">Play</button>
<button style="display:none" id="headsButton">Heads</button>
<button style="display:none" id="tailsButton">Tails</button>
<script src="game.js"></script>
</body>
</html>
Memodifikasi game.js untuk memainkan game balik koin saat tombol "Putar" diklik.
game.js
// Create a coin flip game
class Game {
constructor() {
// Define variables
this.score = 0;
this.choice = '';
this.canvas = document.getElementById('gameContainer').getContext('2d');
this.canvas.font = '24px Arial';
this.playButton = document.getElementById('playButton');
this.headsButton = document.getElementById('headsButton');
this.tailsButton = document.getElementById('tailsButton');
// On click listeners for the game's buttons.
this.playButton.addEventListener('click', () => {
this.erase();
this.play();
});
this.headsButton.addEventListener('click', () => {
this.choice = 'Heads';
this.flipCoin();
});
this.tailsButton.addEventListener('click', () => {
this.choice = 'Tails';
this.flipCoin();
});
this.erase();
}
// Start the game
play() {
this.score = 0;
this.canvas.fillText('Score: ' + this.score, 8, 26);
this.canvas.fillText('Heads or Tails?', 66, 150);
this.playButton.style.display = 'none';
this.headsButton.style.display = 'inline-block';
this.tailsButton.style.display = 'inline-block';
}
// Flip the coin
flipCoin() {
this.headsButton.disabled = true;
this.tailsButton.disabled = true;
this.erase();
this.canvas.fillText('Score: ' + this.score, 8, 26);
this.canvas.fillText('Flipping coin . . .', 60, 150);
setTimeout(() => { this.coinLanded() }, 2000);
}
// Logic for when the coin lands
coinLanded() {
this.headsButton.disabled = false;
this.tailsButton.disabled = false;
let sideUp;
if(Math.random() < 0.5) {
sideUp = 'Heads';
} else {
sideUp = 'Tails';
}
if (sideUp === this.choice ) {
this.win(sideUp);
} else {
this.lose(sideUp);
}
}
// Guess the flip correctly
win(sideUp) {
this.erase();
this.score += 1;
this.canvas.fillText('Score: ' + this.score, 8, 26);
this.canvas.fillText('It was ' + sideUp + '!', 66, 150);
this.canvas.fillText('Guess again', 70, 200);
}
// Guess the flip incorrectly
lose(sideUp) {
this.erase();
this.canvas.fillText('Sorry, it was ' + sideUp, 50, 100);
this.canvas.fillText('Your score was ' + this.score, 50, 150);
this.canvas.fillText('Want to play again?', 45, 200);
this.playButton.style.display = 'inline-block';
this.headsButton.style.display = 'none';
this.tailsButton.style.display = 'none';
}
// Erase the canvas
erase() {
this.canvas.fillStyle = '#ADD8E6';
this.canvas.fillRect(0, 0, 300, 300);
this.canvas.fillStyle = '#000000';
}
}
const game = new Game();
Setelah menyelesaikan langkah ini, saat Anda membuka index.html
di browser (melalui
server pengembangan), Anda akan dapat melihat kanvas game dan tombol "Mainkan".
Jika Anda mengklik Putar, game melempar koin akan dimulai.
3. Mengimpor Ad Placement API
Selanjutnya, tambahkan Ad Placement API ke game Anda dengan menyisipkan tag skrip di
index.html
, sebelum tag untuk game.js
.
Tag skrip dapat mengambil sejumlah parameter. Kami akan menggunakan parameter berikut untuk menentukan kode properti AdSense dan untuk mengaktifkan mode pengujian:
data-ad-client=<AdSense property code>
Kode properti AdSense Anda. Hal ini selalu diperlukan bahkan untuk game yang akan berjalan dalam aplikasi.data-adbreak-test="on"
Mengaktifkan mode pengujian. Hapus ini untuk game setelah ditayangkan kepada pemain.
Siapkan Kode AdSense dan aktifkan mode pengujian
Fungsi Ad Placement API disertakan dalam kode AdSense. Untuk mengaktifkannya, Anda harus menambahkan kode AdSense terlebih dahulu dan menyertakan cuplikan skrip kecil yang menginisialisasi dua fungsi utamanya: adBreak()
dan adConfig()
.
index.html (web)
[...]
<canvas id="gameContainer" height="300px" width="300px"></canvas>
<button id="playButton">Play</button>
<button style="display:none" id="headsButton">Heads</button>
<button style="display:none" id="tailsButton">Tails</button>
<script async
data-adbreak-test="on"
src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-123456789"
crossorigin="anonymous">
</script>
<script>
window.adsbygoogle = window.adsbygoogle || [];
const adBreak = adConfig = function(o) {adsbygoogle.push(o);}
</script>
<script src="game.js"></script>
</body>
</html>
Menyematkan game Anda (opsional)
Jika ingin menyematkan game di halaman lain dalam iFrame, dan tag adsbygoogle
berada di halaman HTML game, pastikan untuk menambahkan allow='autoplay'
ke elemen iframe. Ini adalah praktik terbaik, dan diperlukan agar iklan tertentu memenuhi syarat untuk game Anda.
<head>
<!-- The adsbygoogle tag is not here -->
</head>
<body>
<iframe src="https://www.my-game.com" title="My game" allow="autoplay">
<!-- The game is loaded here and contains the adsbygoogle tag -->
</iframe>
</body>
Mendukung aplikasi seluler
Game H5 dapat berjalan di browser web biasa, atau di WebView atau Tab Khusus Chrome dalam aplikasi. Ad Placement API dapat mendeteksi lingkungan tempat game Anda berjalan dan mengarahkan permintaan iklan dengan tepat. Jika game Anda berjalan dalam browser web biasa, permintaan iklan akan diperlakukan seperti permintaan AdSense biasa. Jika Ad Placement API mendeteksi lingkungan dalam aplikasi, maka aplikasi akan berkomunikasi dengan GMA SDK, jika ada, untuk meminta dan menampilkan iklan AdMob.
Saat ini, kemampuan ini didukung di aplikasi Android yang telah ditautkan dengan GMA SDK AdMob. Untuk mengaktifkannya, Anda harus mendaftarkan WebView yang akan menampilkan game Anda dengan GMA SDK, lalu mengonfigurasi unit iklan AdMob dan meneruskannya sebagai parameter tambahan ke tag AdSense. Saat game Anda berjalan dalam aplikasi yang sesuai, Ad Placement API akan menggunakan unit iklan ini untuk menampilkan iklan.
Untuk mengaktifkan dukungan seluler, Anda harus menentukan parameter tag tambahan berikut:
data-admob-interstitial-slot=<AdMob slot ID>
ID unit iklan interstisial AdMob yang telah Anda konfigurasikan sebelumnya.data-admob-rewarded-slot=<AdMob slot ID>
ID unit iklan reward AdMob.
Kode properti AdSense Anda harus selalu diteruskan dengan parameter data-ad-client
dan setidaknya salah satu dari data-admob-interstitial-slot
atau data-admob-rewarded-slot
harus ditentukan. Kedua parameter harus ditentukan jika game Anda menggunakan kedua format.
Secara opsional, Anda juga dapat menentukan parameter tag data-admob-ads-only=on
untuk
menunjukkan bahwa game Anda hanya boleh menampilkan iklan dari AdMob dan tidak melakukan penggantian ke
AdSense jika game sedang dimainkan di lingkungan yang
tidak mendukung permintaan AdMob (misalnya, lingkungan atau aplikasi non-aplikasi tanpa
konfigurasi GMA SDK AdMob).
Penting: Saat Anda mendesain game untuk disematkan di dalam sebuah aplikasi dan Anda adalah pemilik aplikasi tersebut, atau menyepakati perjanjian bagi hasil dengan pemilik aplikasi tersebut, hanya cara melakukannya dengan cara yang sesuai dengan kebijakan dan dukungan AdMob adalah menggunakan dukungan ini.
Pertama, daftarkan WebView yang akan menampilkan game Anda dengan GMA SDK:
MainActivity.java (aplikasi)
...
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
webView = findViewById(R.id.webview_minigame);
WebSettings settings = webView.getSettings();
settings.setJavaScriptEnabled(true);
h5AdsWebViewClient = new H5AdsWebViewClient(this, webView);
webView.setWebViewClient(h5AdsWebViewClient);
h5AdsWebViewClient.setDelegateWebViewClient(pubWebViewClient);
Berikutnya, teruskan unit iklan AdMob (satu untuk interstisial dan satu lagi untuk iklan reward) sebagai berikut:
index.html (aplikasi)
[...]
<canvas id="gameContainer" height="300px" width="300px"></canvas>
<button id="playButton">Play</button>
<button style="display:none" id="headsButton">Heads</button>
<button style="display:none" id="tailsButton">Tails</button>
<script async
data-admob-interstitial-slot="ca-app-pub-0987654321/1234567890"
data-admob-rewarded-slot="ca-app-pub-0987654321/0987654321"
src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-123456789"
crossorigin="anonymous">
</script>
<script>
window.adsbygoogle = window.adsbygoogle || [];
const adBreak = adConfig = function(o) {adsbygoogle.push(o);}
</script>
<script src="game.js"></script>
</body>
</html>
4. Melakukan panggilan ke adConfig()
Panggilan adConfig()
memberitahukan konfigurasi saat ini game
ke Ad Placement API. API kemudian dapat menggunakan informasi ini untuk memfilter jenis iklan
yang diminta sehingga cocok untuk game tersebut (seperti iklan video yang memerlukan
suara, jika suara diaktifkan).
Panggilan harus dilakukan ke adConfig()
setiap kali konfigurasi ini berubah, seperti
saat pengguna membisukan atau membunyikan audio game. Lakukan panggilan ke adConfig()
di konstruktor
game, lalu tambahkan tombol untuk membisukan dan membunyikan game yang membuat
panggilan adConfig()
tambahan.
game.js
class Game {
constructor() {
// Define variables
this.score = 0;
this.choice = '';
this.muted = false;
this.canvas = document.getElementById('gameContainer').getContext('2d');
this.canvas.font = '24px Arial';
this.playButton = document.getElementById('playButton');
this.headsButton = document.getElementById('headsButton');
this.tailsButton = document.getElementById('tailsButton');
this.muteButton = document.getElementById('muteButton');
adConfig({
sound: 'on',
});
// On click listeners for the game's buttons.
this.playButton.addEventListener('click', () => {
this.erase();
this.play();
});
this.headsButton.addEventListener('click', () => {
this.choice = 'Heads';
this.flipCoin();
});
this.tailsButton.addEventListener('click', () => {
this.choice = 'Tails';
this.flipCoin();
});
this.muteButton.addEventListener('click', () => {
var soundString = this.muted ? 'on' : 'off';
this.muteButton.innerHTML = this.muted ? 'Mute sound' : 'Un-mute sound';
this.muted = !this.muted;
adConfig({
sound: soundString,
});
});
this.erase();
[...]
Sekarang, tambahkan tombol bisukan ke file HTML Anda.
index.html
[...]
<canvas id="gameContainer" height="300px" width="300px"></canvas>
<button id="playButton">Play</button>
<button style="display:none" id="headsButton">Heads</button>
<button style="display:none" id="tailsButton">Tails</button>
<button id="muteButton">Mute sound</button>
<script async
data-adbreak-test="on"
src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-123456789"
crossorigin="anonymous">
</script>
[...]
5. Lakukan panggilan ke adBreak()
saat game berakhir
Panggilan adBreak()
menentukan penempatan iklan dan mengambil objek yang disebut
konfigurasi penempatan yang menentukan semua yang diperlukan untuk menampilkan iklan pada tahap ini
dalam game Anda. Untuk mendukung berbagai jenis iklan, Anda harus menginisialisasi berbagai subset konfigurasi penempatan.
Panggilan adBreak()
menentukan penempatan tempat iklan dapat ditampilkan, atau dengan kata
lain, peluang untuk menampilkan iklan. Apakah iklan benar-benar ditampilkan akan bergantung pada
sejumlah hal:
- Jenis penempatan iklan yang telah Anda deklarasikan.
- Jika ada interaksi pengguna yang sesuai sebelum penempatan iklan ini.
- Apakah ada iklan yang sesuai untuk pemutar saat ini, yang:
- Relevan dengan mereka.
- Sesuai dengan setelan privasi dan izin data masing-masing.
- Jumlah iklan yang dilihat pengguna baru-baru ini.
- Setelan kontrol yang telah Anda konfigurasikan untuk game ini sebagai:
- Petunjuk dalam tag.
- Di AdSense (Catatan: kontrol yang tersedia di AdSense akan berkembang seiring waktu)
Tambahkan kode untuk iklan interstisial yang akan ditampilkan saat game dimulai ulang: lakukan panggilan ke adBreak()
dalam fungsi play()
, yang hanya berjalan setelah game dimainkan sekali.
adBreak()
harus dipanggil sebagai bagian dari tindakan pengguna, seperti mengklik tombol "Putar"
jika tidak, API tidak akan dapat meminta dan menampilkan iklan.
Buat fungsi yang akan dipanggil sebelum dan sesudah jeda iklan, yang kemudian akan Anda gunakan dalam konfigurasi penempatan adBreak()
. Penting untuk diperhatikan bahwa fungsi beforeAd
dan afterAd
hanya akan dipanggil jika iklan yang sesuai ditemukan.
game.js
class Game {
constructor() {
// Define variables
this.score = 0;
this.choice = '';
this.muted = false;
this.shouldShowAdOnPlay = false;
[...]
// Start the game
play() {
if (this.shouldShowAdOnPlay) {
this.shouldShowAdOnPlay = false;
adBreak({
type: 'next', // ad shows at start of next level
name: 'restart-game',
beforeAd: () => { this.disableButtons(); }, // You may also want to mute the game's sound.
afterAd: () => { this.enableButtons(); }, // resume the game flow.
});
}
this.score = 0;
this.canvas.fillText('Score: ' + this.score, 8, 26);
this.canvas.fillText('Heads or Tails?', 66, 150);
this.playButton.style.display = 'none'
this.headsButton.style.display = 'inline-block'
this.tailsButton.style.display = 'inline-block'
}
[...]
// Guess the flip incorrectly
lose(sideUp) {
this.erase()
this.canvas.fillText('Sorry, it was ' + sideUp, 50, 100);
this.canvas.fillText('Your score was ' + this.score, 50, 150);
this.canvas.fillText('Want to play again?', 45, 200);
this.playButton.style.display = 'inline-block'
this.headsButton.style.display = 'none'
this.tailsButton.style.display = 'none'
this.shouldShowAdOnPlay = true;
}
[...]
// Erase the canvas
erase() {
this.canvas.fillStyle = '#ADD8E6';
this.canvas.fillRect(0, 0, 300, 300);
this.canvas.fillStyle = '#000000';
}
enableButtons() {
this.playButton.disabled = false;
this.headsButton.disabled = false;
this.tailsButton.disabled = false;
}
disableButtons() {
this.playButton.disabled = true;
this.headsButton.disabled = true;
this.tailsButton.disabled = true;
}
}
const game = new Game();
Aplikasi balik koin kini membuat penempatan iklan agar iklan dapat ditampilkan.
Aplikasi Anda sendiri mungkin memiliki tempat tambahan yang sesuai untuk iklan selain saat game berakhir. Memanggil adBreak()
di tempat tersebut harus mirip dengan contoh ini.
Menonaktifkan pengujian untuk aplikasi produksi
Sebelum merilis aplikasi, penting untuk menghapus atau mengomentari baris
data-adbreak-test="on"
di index.html
, karena kode ini mengaktifkan setelan pengujian dalam
produksi.