หน้านี้ได้รับการแปลโดย Cloud Translation API

ตัวอย่างการติดตั้งใช้งาน

Ad Placement API ออกแบบมาเพื่อรองรับนักพัฒนาแอปของ AdSense และ AdMob ที่ใช้โฆษณาคั่นระหว่างหน้าและโฆษณาที่มีการให้รางวัลในเกม HTML5 บนเว็บหรือภายในแอป ตัวอย่างนี้สาธิตวิธีผสานรวม API ตําแหน่งโฆษณาลงในเกม และใช้เพื่อวางโฆษณาคั่นระหว่างหน้า

สิ่งที่ต้องมีก่อน

ก่อนที่จะเริ่มต้น คุณต้องมีสิ่งต่อไปนี้

สร้างไฟล์เปล่า 2 ไฟล์ในไดเรกทอรีเดียวกัน โดยทําดังนี้
- index.html
- Game.js
ติดตั้ง Python ในเครื่องหรือใช้เว็บเซิร์ฟเวอร์เพื่อทดสอบการใช้งาน

โค้ดตัวอย่างของแอป

ผู้เผยแพร่โฆษณา AdMob สามารถดาวน์โหลดโค้ดตัวอย่างแอปเพื่อให้เข้าใจมากยิ่งขึ้นว่าจะผสานรวม API เข้ากับเกมแอปได้อย่างไร

ดาวน์โหลดโค้ดตัวอย่างของแอป

1. เริ่มต้นเซิร์ฟเวอร์การพัฒนา

เนื่องจาก API ตําแหน่งโฆษณาจะโหลดทรัพยากร Dependency ผ่านโปรโตคอลเดียวกับหน้าเว็บที่โหลด คุณจึงต้องใช้เว็บเซิร์ฟเวอร์เพื่อทดสอบแอป ใช้เซิร์ฟเวอร์ในตัวของ Python&#39 เพื่อสร้างสภาพแวดล้อมการพัฒนาในเครื่องได้

เปิดเทอร์มินัล
ไปที่ไดเรกทอรีที่มีไฟล์ index.html แล้วเรียกใช้
```
python -m http.server 8000
```
หมายเหตุ: http.server ใช้ได้เฉพาะใน Python 3.x
ไปที่ localhost:8000 ในเว็บเบราว์เซอร์

คุณยังใช้เว็บเซิร์ฟเวอร์อื่นๆ เช่น เซิร์ฟเวอร์ HTTP ของ Apache ได้อีกด้วย

2. สร้างเกม HTML5

แก้ไข index.html เพื่อสร้างเอลิเมนต์ Canvas ของ HTML5 และปุ่มที่ทริกเกอร์การเล่นเกม จากนั้นเพิ่มแท็กสคริปต์ที่จําเป็นเพื่อโหลดไฟล์ 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>

แก้ไข Game.js เพื่อเล่นเกมโยนเหรียญเมื่อมีการคลิกปุ่ม ""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();

หลังจากทําตามขั้นตอนนี้เสร็จแล้ว เมื่อเปิด index.html ในเบราว์เซอร์ (ผ่านเซิร์ฟเวอร์การพัฒนา) คุณจะเห็น Canvas ของเกมและปุ่ม "Play" หากคุณคลิกเล่น เกมหยอดเหรียญควรเริ่มต้นเอง

3. นําเข้า API ตําแหน่งโฆษณา

ต่อไป ให้เพิ่ม Ad Placement API ลงในเกมโดยแทรกแท็กสคริปต์ใน index.html ก่อนแท็กสําหรับ game.js

แท็กสคริปต์สามารถใช้พารามิเตอร์ได้จํานวนหนึ่ง เราจะใช้พารามิเตอร์ต่อไปนี้เพื่อระบุรหัสพร็อพเพอร์ตี้ AdSense และเปิดใช้โหมดการทดสอบ

data-ad-client=<AdSense property code> รหัสพร็อพเพอร์ตี้ AdSense คุณจําเป็นต้องทําเช่นนี้เสมอสําหรับเกมที่จะทํางานภายในแอป
data-adbreak-test="on" เปิดใช้โหมดทดสอบ นําสิ่งนี้ออกสําหรับเกมเมื่อให้บริการกับผู้เล่น

ตั้งค่าโค้ด AdSense และเปิดโหมดทดสอบ

ฟังก์ชันการทํางานของ Ad Placement API รวมอยู่ในโค้ดของ AdSense ในการเปิดใช้ คุณต้องเพิ่มโค้ด AdSense และใส่ข้อมูลโค้ดสคริปต์เล็กๆ ที่เริ่มต้นฟังก์ชันหลัก 2 อย่าง ได้แก่ adBreak() และ adConfig() ก่อน

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>

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

การฝังเกม (ไม่บังคับ)

หากต้องการฝังเกมในหน้าอื่นๆ ภายใน iframe และแท็ก adsbygoogle อยู่ในหน้า HTML ของเกม ให้เพิ่ม allow='autoplay' ลงในองค์ประกอบ iframe ซึ่งเป็นแนวทางปฏิบัติที่ดีที่สุดและจําเป็นต้องทําให้โฆษณาบางรายการมีสิทธิ์แสดงเกมของคุณ

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

รองรับแอปบนอุปกรณ์เคลื่อนที่

เกม H5 ทํางานได้ในเว็บเบราว์เซอร์ทั่วไป หรือใน WebView หรือแท็บที่กําหนดเองของ Chrome ภายในแอป โดย Ad Placement API จะตรวจหาสภาพแวดล้อมที่เกมทํางานอยู่และส่งคําขอโฆษณาโดยตรงได้อย่างเหมาะสม หากเกมกําลังทํางานในเว็บเบราว์เซอร์ปกติ คําขอโฆษณาจะได้รับการปฏิบัติเหมือนคําขอปกติของ AdSense หาก Ad Placement API ตรวจพบสภาพแวดล้อมในแอป ก็จะสื่อสารกับ GMA SDK (หากมี) เพื่อขอและแสดงโฆษณา AdMob

ปัจจุบันความสามารถนี้ใช้ได้ในแอป Android ที่ลิงก์กับ AdMob GMA SDK หากต้องการเปิดใช้ คุณต้องลงทะเบียน WebView ที่จะแสดงเกมของคุณกับ GMA SDK จากนั้นกําหนดค่าหน่วยโฆษณา AdMob และส่งพารามิเตอร์เหล่านั้นเป็นพารามิเตอร์เพิ่มเติมไปยังแท็ก AdSense เมื่อเกมทํางานภายในแอปที่เหมาะสม Ad Placement API จะใช้หน่วยโฆษณาเหล่านี้เพื่อแสดงโฆษณา

หากต้องการเปิดใช้การรองรับอุปกรณ์เคลื่อนที่ คุณต้องระบุพารามิเตอร์แท็กเพิ่มเติมต่อไปนี้

data-admob-interstitial-slot=<AdMob slot ID> รหัสหน่วยโฆษณาคั่นระหว่างหน้าของ AdMob ที่คุณเคยกําหนดค่าไว้ก่อนหน้านี้
data-admob-rewarded-slot=<AdMob slot ID> รหัสหน่วยโฆษณาที่มีการให้รางวัลของ AdMob

รหัสพร็อพเพอร์ตี้ AdSense ควรส่งผ่านพารามิเตอร์ data-ad-client เสมอ และต้องระบุอย่างน้อย data-admob-interstitial-slot หรือ data-admob-rewarded-slot อย่างน้อย 1 รายการ พารามิเตอร์ทั้ง 2 แบบควรระบุไว้หากเกมใช้ทั้ง 2 รูปแบบ

นอกจากนี้ คุณยังระบุพารามิเตอร์แท็ก data-admob-ads-only=on เพื่อระบุว่าเกมควรแสดงโฆษณาจาก AdMob เท่านั้น ไม่ใช่สํารองไปยัง AdSense ในกรณีที่เกมดังกล่าวเล่นอยู่ในสภาพแวดล้อมที่ไม่รองรับคําขอ AdMob (เช่น สภาพแวดล้อมที่ไม่ใช่แอปหรือแอปที่ไม่มีการกําหนดค่า GMA SDK ของ AdMob)

สําคัญ: เมื่อออกแบบเกมให้ฝังอยู่ในแอปและคุณเป็นเจ้าของแอป หรือเข้าร่วมข้อตกลงส่วนแบ่งรายได้กับเจ้าของแอป การใช้วิธีการเพียงอย่างเดียวเท่านั้น<b>

ก่อนอื่นให้ลงทะเบียน WebView ที่จะแสดงเกมของคุณด้วย GMA SDK

MainActivity.java (แอป)

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

ต่อไป ให้ส่งหน่วยโฆษณา AdMob (หนึ่งหน่วยสําหรับโฆษณาคั่นระหว่างหน้าและหน่วยโฆษณาหนึ่งสําหรับโฆษณาที่มีการให้รางวัล) ดังนี้

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>
    <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. เรียกใช้ adConfig()

การเรียก adConfig() จะแจ้งการกําหนดค่าปัจจุบันของเกมกับ Ad Placement API จากนั้น API จะใช้ข้อมูลนี้เพื่อกรองประเภทโฆษณา ที่ขอให้เหมาะกับประเภทเกม (เช่น โฆษณาวิดีโอที่ต้องใช้เสียงหากเปิดใช้เสียง)

ควรเรียก adConfig() ทุกครั้งที่มีการเปลี่ยนแปลงการกําหนดค่านี้ เช่น เมื่อผู้ใช้ปิดเสียงหรือเปิดเสียงเกม เรียก adConfig() ในเครื่องมือสร้างเกม จากนั้นเพิ่มปุ่มเพื่อปิดเสียงและเปิดเสียงเกมที่เรียกใช้ adConfig() เพิ่มเติม

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

จากนั้นเพิ่มปุ่มปิดเสียงลงในไฟล์ HTML

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. โทรหา `adBreak()` เมื่อสิ้นสุดการแข่งขัน

การเรียก adBreak() จะกําหนดตําแหน่งโฆษณาและใช้ออบเจ็กต์ที่เรียกว่าการกําหนดค่าตําแหน่งซึ่งระบุทุกอย่างที่จําเป็นในการแสดงโฆษณา ณ จุดนี้ในเกมของคุณ การรองรับโฆษณาประเภทต่างๆ จะทําให้คุณเริ่มต้นการกําหนดค่าตําแหน่งโฆษณาที่ต่างกันบางส่วนได้

การเรียก adBreak() จะกําหนดตําแหน่งที่โฆษณามีโอกาสแสดง หรือกล่าวคือ เป็นโอกาสในการแสดงโฆษณา การแสดงโฆษณาจะขึ้นอยู่กับ ปัจจัยหลายอย่างต่อไปนี้

ประเภทของตําแหน่งโฆษณาที่คุณประกาศ
หากมีการโต้ตอบกับผู้ใช้ที่เหมาะสมก่อนตําแหน่งโฆษณานี้
มีโฆษณาที่เหมาะสมสําหรับผู้เล่นปัจจุบันหรือไม่ โดยทําดังนี้
- ซึ่งเกี่ยวข้องกับพวกเขา
- สอดคล้องกับการตั้งค่าความเป็นส่วนตัวของข้อมูลและการขอความยินยอม
จํานวนโฆษณาที่ผู้ใช้ดูเมื่อเร็วๆ นี้
การตั้งค่าการควบคุมที่คุณกําหนดค่าสําหรับเกมนี้เป็นดังนี้
- คําแนะนําในแท็ก
- ใน AdSense (หมายเหตุ: การควบคุมที่มีอยู่ใน AdSense จะพัฒนาไปตามเวลา)

เพิ่มโค้ดสําหรับโฆษณาคั่นระหว่างหน้าที่จะแสดงเมื่อเกมรีสตาร์ท: เรียกใช้ adBreak() ในฟังก์ชัน play() ซึ่งจะทํางานหลังจากเกมเล่นจบเพียงครั้งเดียวเท่านั้น

ต้องเรียก adBreak() เป็นส่วนหนึ่งของการกระทําของผู้ใช้ เช่น การคลิกปุ่ม "Play" ไม่เช่นนั้น API จะไม่สามารถขอและแสดงโฆษณาได้

สร้างฟังก์ชันที่จะเรียกก่อนและหลังช่วงพักโฆษณา ซึ่งจะใช้ในการกําหนดค่าตําแหน่ง adBreak() โปรดทราบว่าระบบจะเรียกใช้ฟังก์ชัน beforeAd และ afterAd เมื่อพบโฆษณาที่เหมาะสมเท่านั้น

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

ตอนนี้แอปพลิกเหรียญกําลังสร้างตําแหน่งโฆษณาเพื่อให้โฆษณาแสดง

แอปของคุณเองอาจมีสถานที่เพิ่มเติมที่เหมาะสมสําหรับโฆษณานอกเหนือจากเมื่อเกมจบลง การเรียกใช้ adBreak() ในที่ดังกล่าวควรคล้ายคลึงกับตัวอย่างนี้

ปิดการทดสอบสําหรับแอปเวอร์ชันที่ใช้งานจริง

ก่อนที่จะเปิดตัวแอป คุณต้องนําบรรทัด data-adbreak-test="on" ใน index.html ออกหรือแสดงความคิดเห็น เนื่องจากโค้ดนี้จะเปิดการตั้งค่าการทดสอบในเวอร์ชันที่ใช้งานจริง

ตัวอย่างการติดตั้งใช้งาน

สิ่งที่ต้องมีก่อน

โค้ดตัวอย่างของแอป

1. เริ่มต้นเซิร์ฟเวอร์การพัฒนา

2. สร้างเกม HTML5

index.html

Game.js

3. นําเข้า API ตําแหน่งโฆษณา

ตั้งค่าโค้ด AdSense และเปิดโหมดทดสอบ

index.html (เว็บ)

การฝังเกม (ไม่บังคับ)

รองรับแอปบนอุปกรณ์เคลื่อนที่

MainActivity.java (แอป)

index.html (แอป)

4. เรียกใช้ adConfig()

Game.js

index.html

5. โทรหา adBreak() เมื่อสิ้นสุดการแข่งขัน

Game.js

ปิดการทดสอบสําหรับแอปเวอร์ชันที่ใช้งานจริง

5. โทรหา `adBreak()` เมื่อสิ้นสุดการแข่งขัน