Halaman ini diterjemahkan oleh Cloud Translation API.

Contoh implementasi

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.

Download kode contoh 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
```
Catatan: http.server hanya tersedia di Python 3.x.
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.

Contoh implementasi

Prasyarat

Kode contoh aplikasi

1. Memulai server pengembangan

2. Membuat game HTML5

index.html

game.js

3. Mengimpor Ad Placement API

Siapkan Kode AdSense dan aktifkan mode pengujian

index.html (web)

Menyematkan game Anda (opsional)

Mendukung aplikasi seluler

MainActivity.java (aplikasi)

index.html (aplikasi)

4. Melakukan panggilan ke adConfig()

game.js

index.html

5. Lakukan panggilan ke adBreak() saat game berakhir

game.js

Menonaktifkan pengujian untuk aplikasi produksi

5. Lakukan panggilan ke `adBreak()` saat game berakhir