این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اجرای نمونه

Ad Placement API برای پشتیبانی از توسعه دهندگان AdSense و AdMob با استفاده از تبلیغات بینابینی و پاداش در بازی های HTML5 در وب یا درون برنامه ها طراحی شده است. این مثال نحوه ادغام Ad Placement API را در یک بازی و استفاده از آن برای قرار دادن یک تبلیغ بینابینی نشان می دهد.

پیش نیازها

قبل از شروع به موارد زیر نیاز دارید:

دو فایل خالی در یک دایرکتوری ایجاد کنید:
- index.html
- game.js
پایتون را به صورت محلی نصب کنید یا از وب سرور برای آزمایش پیاده سازی خود استفاده کنید

کد نمونه برنامه

ناشران AdMob می‌توانند نمونه کد برنامه را دانلود کنند تا درک بهتری از نحوه ادغام API در یک بازی برنامه داشته باشند.

کد نمونه برنامه را دانلود کنید

1. یک سرور توسعه راه اندازی کنید

از آنجایی که Ads Placement API وابستگی‌ها را از طریق همان پروتکل صفحه‌ای که در آن بارگذاری شده است بارگیری می‌کند، باید از یک وب سرور برای آزمایش برنامه خود استفاده کنید. شما می توانید از سرور داخلی پایتون برای ایجاد یک محیط توسعه محلی استفاده کنید.

ترمینال را باز کنید.
به دایرکتوری که حاوی فایل index.html شماست بروید، سپس اجرا کنید:
```
python -m http.server 8000
```
توجه: http.server فقط در پایتون 3.x موجود است.
در یک مرورگر وب، به localhost:8000 بروید

همچنین می توانید از هر وب سرور دیگری مانند Apache HTTP Server استفاده کنید.

2. یک بازی HTML5 ایجاد کنید

برای ایجاد یک عنصر بوم HTML5 و یک دکمه برای شروع بازی، index.html را تغییر دهید. سپس تگ اسکریپت لازم را برای بارگذاری فایل 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 را تغییر دهید تا یک بازی برگرداندن سکه انجام دهید.

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 را در مرورگر خود باز می کنید (از طریق سرور توسعه خود) باید بتوانید بوم بازی و دکمه "Play" را مشاهده کنید. اگر روی Play کلیک کنید، بازی برگرداندن سکه باید شروع شود.

3. Ad Placement API را وارد کنید

سپس، با قرار دادن یک برچسب اسکریپت در index.html ، قبل از برچسب game.js ، Ad Placement API را به بازی خود اضافه کنید.

تگ اسکریپت می تواند تعدادی پارامتر داشته باشد. ما از پارامترهای زیر برای تعیین کد ویژگی AdSense و فعال کردن حالت آزمایش استفاده خواهیم کرد:

data-ad-client= <AdSense property code> دارایی AdSense شما. این همیشه حتی برای بازی هایی که در داخل برنامه ها اجرا می شوند مورد نیاز است.
data-adbreak-test="on" حالت تست را فعال می کند. این را برای بازی‌ها پس از ارائه به بازیکنان حذف کنید.

کد AdSense را تنظیم کنید و حالت تست را روشن کنید

قابلیت Ad Placement API در کد AdSense گنجانده شده است. برای روشن کردن آن، ابتدا باید کد AdSense را اضافه کنید و یک قطعه اسکریپت کوچک را اضافه کنید که دو عملکرد کلیدی آن را مقداردهی اولیه می کند: 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 را درخواست کند و نشان دهد.

در حال حاضر، این قابلیت در برنامه‌های اندرویدی که با 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 باید مشخص شود. اگر بازی شما از هر دو فرمت استفاده می کند، هر دو پارامتر باید مشخص شوند.

به صورت اختیاری، می‌توانید پارامتر برچسب data-admob-ads-only=on را نیز مشخص کنید تا نشان دهد که بازی شما باید تبلیغات را فقط از AdMob نشان دهد و در مواردی که بازی در محیطی اجرا می‌شود که پشتیبانی نمی‌کند، به AdSense بازگشتی نداشته باشد. درخواست‌های AdMob (مثلاً محیط‌های غیربرنامه‌ای یا برنامه‌های بدون پیکربندی AdMob GMA SDK).

مهم : زمانی که بازی خود را طوری طراحی می‌کنید که در یک برنامه جاسازی شود و مالک برنامه هستید، یا در حال امضای قرارداد سهم درآمد با مالک برنامه هستید، تنها راه انجام این کار با عملکرد بالا و مطابق با خط‌مشی این است. برای استفاده از این پشتیبانی AdMob.

ابتدا 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();

اپلیکیشن coin flip اکنون در حال ایجاد مکان های تبلیغاتی برای نمایش تبلیغات است.

برنامه خودتان ممکن است مکان‌های اضافی و مناسبی برای تبلیغات غیر از زمان پایان بازی داشته باشد. فراخوانی adBreak() در آن مکان ها باید مشابه این مثال باشد.

تست برنامه های تولیدی را خاموش کنید

قبل از انتشار برنامه، مهم است که خط data-adbreak-test="on" در index.html حذف یا نظر دهید، زیرا این کد تنظیمات آزمایشی را در تولید روشن می‌کند.

اجرای نمونه

پیش نیازها

کد نمونه برنامه

1. یک سرور توسعه راه اندازی کنید

2. یک بازی HTML5 ایجاد کنید

index.html

game.js

3. Ad Placement API را وارد کنید

کد AdSense را تنظیم کنید و حالت تست را روشن کنید

index.html (وب)

جاسازی بازی شما (اختیاری)

پشتیبانی از اپلیکیشن های موبایل

MainActivity.java (برنامه)

index.html (برنامه)

4. با ()adConfig تماس بگیرید

game.js

index.html

5. پس از پایان بازی با adBreak() تماس بگیرید

game.js

تست برنامه های تولیدی را خاموش کنید

5. پس از پایان بازی با `adBreak()` تماس بگیرید