Ví dụ về cách triển khai

API Vị trí đặt quảng cáo được thiết kế để hỗ trợ các nhà phát triển AdSense và AdMob sử dụng quảng cáo xen kẽ và quảng cáo có tặng thưởng trong trò chơi HTML5 trên web hoặc trong ứng dụng. Ví dụ này minh hoạ cách tích hợp API Vị trí đặt quảng cáo vào một trò chơi và sử dụng API đó để đặt quảng cáo xen kẽ.

Điều kiện tiên quyết

Trước khi bắt đầu, bạn cần có:

  • Tạo 2 tệp trống trong cùng một thư mục:
    • index.html
    • game.js
  • Cài đặt Python cục bộ hoặc sử dụng một máy chủ web để kiểm thử kết quả triển khai

Mã mẫu ứng dụng

Nhà xuất bản AdMob có thể tải mã ứng dụng mẫu xuống để hiểu rõ hơn về cách tích hợp API vào trò chơi.

Tải mã mẫu ứng dụng xuống

1. Khởi động máy chủ phát triển

Vì API Vị trí đặt quảng cáo tải các phần phụ thuộc thông qua cùng một giao thức với trang mà tệp đó được tải, nên bạn cần sử dụng một máy chủ web để kiểm thử ứng dụng của mình. Bạn có thể sử dụng máy chủ tích hợp của Python để tạo môi trường phát triển cục bộ.

  1. Mở cửa sổ dòng lệnh.

  2. Chuyển đến thư mục chứa tệp index.html của bạn, sau đó chạy:

    python -m http.server 8000

  3. Trên trình duyệt web, hãy truy cập vào localhost:8000

Bạn cũng có thể sử dụng bất kỳ máy chủ web nào khác, chẳng hạn như Máy chủ HTTP Apache.

2. Tạo trò chơi HTML5

Sửa đổi index.html để tạo một phần tử canvas HTML5 và một nút để kích hoạt trò chơi. Sau đó, hãy thêm thẻ tập lệnh cần thiết để tải tệp 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>

Sửa đổi game.js để chơi trò chơi lật đồng xu khi nhấp vào nút "Play"

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

Sau khi hoàn tất bước này, khi mở index.html trong trình duyệt (thông qua máy chủ phát triển), bạn có thể thấy canvas trò chơi và nút "Play" Nếu bạn nhấp vào Play, trò chơi tung đồng xu sẽ bắt đầu.

3. Nhập API Vị trí đặt quảng cáo

Tiếp theo, hãy thêm API Vị trí đặt quảng cáo vào trò chơi bằng cách chèn một thẻ tập lệnh vào index.html, trước thẻ cho game.js.

Thẻ trong tập lệnh có thể nhận một số thông số. Chúng tôi sẽ sử dụng các thông số sau để chỉ định mã thuộc tính AdSense và để bật chế độ thử nghiệm:

  • data-ad-client=<AdSense property code> Mã thuộc tính AdSense của bạn. Điều này luôn là bắt buộc ngay cả đối với những trò chơi sẽ chạy trong ứng dụng.
  • data-adbreak-test="on" Bật chế độ thử nghiệm. Hãy xoá nội dung này khỏi trò chơi khi chúng được phân phát cho người chơi.

Thiết lập mã AdSense và bật chế độ thử nghiệm

Chức năng API Vị trí đặt quảng cáo được bao gồm trong mã AdSense. Để bật mã này, trước tiên bạn phải thêm mã AdSense và bao gồm một đoạn mã tập lệnh nhỏ để khởi chạy hai hàm chính: adBreak() và 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>

Nhúng trò chơi của bạn (không bắt buộc)

Nếu bạn muốn nhúng một trò chơi vào các trang khác bên trong iFrame và thẻ adsbygoogle nằm trong trang HTML của trò chơi, hãy nhớ thêm allow='autoplay' vào phần tử iframe. Đây là phương pháp hay nhất và cần thiết để một số quảng cáo nhất định đủ điều kiện cho trò chơi của bạn.

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

Hỗ trợ ứng dụng dành cho thiết bị di động

Trò chơi H5 có thể chạy trong trình duyệt web thông thường, hoặc trong WebView hoặc thẻ Tuỳ chỉnh Chrome trong một ứng dụng. API Vị trí đặt quảng cáo có thể phát hiện môi trường mà trò chơi của bạn đang chạy và chuyển hướng các yêu cầu quảng cáo một cách thích hợp. Nếu trò chơi của bạn đang chạy trong một trình duyệt web thông thường, thì các yêu cầu quảng cáo sẽ được coi như các yêu cầu thông thường của AdSense. Nếu phát hiện một môi trường trong ứng dụng, API Vị trí đặt quảng cáo sẽ thông báo với SDK GMA (nếu có) để yêu cầu và hiển thị quảng cáo của AdMob.

Hiện tại, tính năng này được hỗ trợ trên các ứng dụng Android đã được liên kết với SDK GMA của AdMob. Để bật SDK này, bạn cần đăng ký WebView để hiển thị trò chơi của bạn với SDK GMA, sau đó định cấu hình các đơn vị quảng cáo AdMob và chuyển các thông số đó dưới dạng thông số bổ sung cho thẻ AdSense. Khi trò chơi của bạn chạy trong một ứng dụng phù hợp, API Vị trí đặt quảng cáo sẽ sử dụng các đơn vị quảng cáo này để hiển thị quảng cáo.

Để bật tính năng hỗ trợ thiết bị di động, bạn phải chỉ định các thông số thẻ bổ sung sau:

  • data-admob-interstitial-slot=<AdMob slot ID> Mã đơn vị quảng cáo xen kẽ của AdMob mà bạn đã định cấu hình trước đó.
  • data-admob-rewarded-slot=<AdMob slot ID> Mã đơn vị quảng cáo có tặng thưởng của AdMob.

Mã tài sản AdSense của bạn phải luôn được truyền bằng tham số data-ad-client, đồng thời phải chỉ định ít nhất một trong các data-admob-interstitial-slot hoặc data-admob-rewarded-slot. Bạn nên chỉ định cả hai thông số nếu trò chơi sử dụng cả hai định dạng.

Nếu muốn, bạn cũng có thể chỉ định thông số thẻ data-admob-ads-only=on để cho biết rằng trò chơi của bạn chỉ nên hiển thị quảng cáo từ AdMob và không dự phòng cho AdSense trong trường hợp trò chơi đang được chơi trong một môi trường không hỗ trợ các yêu cầu của AdMob (ví dụ: môi trường không phải ứng dụng hoặc ứng dụng không được định cấu hình SDK GMA cho AdMob).

Lưu ý quan trọng: Khi bạn thiết kế trò chơi để được nhúng trong một ứng dụng và bạn sở hữu ứng dụng đó hoặc ký kết một thỏa thuận chia sẻ doanh thu với chủ sở hữu của ứng dụng, thì cách duy nhất để thực hiện việc này theo cách hiệu quả và tuân thủ chính sách là sử dụng chức năng hỗ trợ AdMob này.

Trước tiên, hãy đăng ký WebView sẽ hiển thị trò chơi của bạn bằng SDK GMA:

MainActivity.java (ứng dụng)

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

Tiếp theo, hãy chuyển đơn vị quảng cáo AdMob (một đơn vị cho quảng cáo xen kẽ và một đơn vị cho quảng cáo có tặng thưởng) như sau:

index.html (ứng dụng)

 [...]
    <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. Gọi đến adConfig()

Lệnh gọi adConfig() sẽ thông báo cấu hình hiện tại của trò chơi cho API Vị trí đặt quảng cáo. Sau đó, API này có thể sử dụng thông tin này để lọc các loại quảng cáo yêu cầu để phù hợp với trò chơi (chẳng hạn như quảng cáo dạng video yêu cầu âm thanh, nếu có bật âm thanh).

Bạn nên thực hiện lệnh gọi đến adConfig() bất cứ khi nào cấu hình này thay đổi, chẳng hạn như khi người dùng tắt tiếng hoặc bật tiếng trò chơi. Gọi đến adConfig() trong hàm khởi tạo trò chơi, sau đó thêm một nút để tắt tiếng và bật tiếng cho trò chơi để thực hiện lệnh gọi adConfig() bổ sung.

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();
  [...]

Bây giờ, hãy thêm nút tắt tiếng vào tệp HTML của bạn.

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. Gọi đến adBreak() khi trò chơi kết thúc

Lệnh gọi adBreak() xác định một vị trí đặt quảng cáo và lấy đối tượng có tên là cấu hình vị trí để chỉ định mọi thứ cần thiết để hiển thị quảng cáo tại thời điểm này trong trò chơi của bạn. Việc hỗ trợ các loại quảng cáo khác nhau sẽ yêu cầu bạn khởi chạy nhiều tập hợp con của cấu hình vị trí.

Lệnh gọi adBreak() xác định một vị trí mà quảng cáo có thể hiển thị, hay nói cách khác là cơ hội hiển thị quảng cáo. Việc một quảng cáo có thực sự hiển thị hay không sẽ phụ thuộc vào một số yếu tố:

  • Loại vị trí đặt quảng cáo mà bạn đã khai báo.
  • Có các tương tác phù hợp của người dùng trước vị trí đặt quảng cáo này.
  • Liệu có quảng cáo phù hợp cho trình phát hiện tại hay không:
    • Phù hợp với người đó.
    • Phù hợp với chế độ cài đặt về quyền riêng tư và sự đồng ý của dữ liệu của người dùng.
  • Số lượng quảng cáo mà người dùng đã xem gần đây.
  • Chế độ cài đặt điều khiển mà bạn đã định cấu hình cho trò chơi này như sau:
    • Gợi ý trong thẻ.
    • Trên AdSense (Lưu ý: các chế độ kiểm soát có sẵn trong AdSense sẽ thay đổi theo thời gian)

Thêm mã cho quảng cáo xen kẽ để hiển thị khi trò chơi khởi động lại: thực hiện lệnh gọi đến adBreak() bên trong hàm play(). Hàm này chỉ chạy sau khi trò chơi đã phát một lần.

adBreak() phải được gọi như một phần của hành động người dùng, chẳng hạn như nhấp vào nút "Play". Nếu không, API sẽ không thể yêu cầu và hiển thị quảng cáo.

Tạo các hàm được gọi trước và sau điểm chèn quảng cáo mà bạn sẽ sử dụng trong cấu hình vị trí adBreak(). Bạn cần lưu ý rằng hàm beforeAd và afterAd sẽ chỉ được gọi nếu tìm thấy quảng cáo phù hợp.

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

Ứng dụng tung tiền xu hiện đang tạo vị trí đặt quảng cáo để quảng cáo hiển thị.

Ứng dụng của riêng bạn có thể có các vị trí bổ sung thích hợp cho quảng cáo, trừ khi trò chơi kết thúc. Việc gọi adBreak() ở những nơi đó sẽ tương tự như ví dụ này.

Tắt thử nghiệm đối với ứng dụng sản xuất

Trước khi phát hành ứng dụng, bạn cần xóa hoặc nhận xét dòng data-adbreak-test="on" trong index.html, vì mã này sẽ bật chế độ cài đặt kiểm thử trong quá trình sản xuất.