דף זה תורגם על ידי Cloud Translation API.

הטמעה לדוגמה

ה-Ad Placement API מיועד לתמוך ב-AdSense ובמפתחים של AdMob באמצעות מודעות מעברון ומודעות מתגמלות במשחקי HTML5 באינטרנט או באפליקציות. בדוגמה זו נדגים איך משלבים את Ad Placement API במשחק ומשתמשים בו כדי למקם מודעת מעברון.

דרישות מוקדמות

לפני שמתחילים, צריך:

יוצרים שני קבצים ריקים באותה ספרייה:
- index.html
- Game.js
ניתן להתקין את Python באופן מקומי או להשתמש בשרת אינטרנט כדי לבדוק את ההטמעה

קוד לדוגמה של אפליקציה

בעלי אפליקציות ב-AdMob יכולים להוריד קוד אפליקציה לדוגמה כדי להבין טוב יותר איך אפשר לשלב את ה-API במשחק אפליקציה.

הורדת קוד לדוגמה של אפליקציה

1. הפעלת שרת פיתוח

מכיוון ש-Ads Placement API טוען יחסי תלות דרך אותו פרוטוקול של הדף שבו הוא נטען, עליכם להשתמש בשרת אינטרנט כדי לבדוק את האפליקציה שלכם. אפשר להשתמש בשרת המובנה של Python&39 כדי ליצור סביבת פיתוח מקומית.

פותחים את הטרמינל.
נכנסים לספרייה שמכילה את הקובץ index.html, ולאחר מכן מריצים את הקובץ:
```
python -m http.server 8000
```
הערה: http.server זמין רק ב-Python 3.x.
בדפדפן האינטרנט, נכנסים לכתובת localhost:8000

תוכלו גם להשתמש בכל שרת אינטרנט אחר, כגון שרת Apache HTTP.

2. יצירת משחק HTML5

יש לשנות את index.html כדי ליצור רכיב קנבס מסוג 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 בדפדפן (באמצעות שרת הפיתוח), תוכלו לראות את לוח הציור של המשחק ואת הלחצן "Play" אם לוחצים על 'הפעלה', משחק ההיפוך של המטבע אמור להתחיל.

3. מייבאים את Ad Placement API

בשלב הבא, מוסיפים למשחק את ה-API של מיקום המודעה על ידי הוספת תג סקריפט index.html לפני התג game.js.

תג הסקריפט יכול לכלול כמה פרמטרים. נשתמש בפרמטרים הבאים כדי לציין את קוד הנכס ב-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.

בשלב זה, היכולת הזו נתמכת באפליקציות 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. יש לציין את שני הפרמטרים אם המשחק משתמש בשני הפורמטים.

אפשר גם לציין פרמטר תג של data-admob-ads-only=on כדי לציין שהמשחק אמור להציג מודעות רק מ-AdMob, ולא לחזור ל-AdSense במקרים שבהם המשחק פועל בסביבה שבה אין תמיכה בבקשות ל-AdMob (למשל, סביבות או אפליקציות שאינן של AdMob שאינן מוגדרות ב-AdMob GMA SDK).

חשוב: כשמעצבים משחק שמיועד להטמעה באפליקציה והמשחק בבעלותכם, או שחתמתם על הסכם חלוקת הכנסות עם הבעלים של האפליקציה, הדרך היחידה לעשות זאת באופן שמניב ביצועים גבוהים ותואם למדיניות היא שימוש בתמיכת AdMob הזו.

ראשית, רושמים את ה-WebView שיציג את המשחק שלכם באמצעות GMA SDK:

יישום ראשי (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() מגדירה מיקום מודעה ומשתמשת באובייקט בשם 'config config' המציין את כל מה שנדרש להצגת מודעה בשלב זה במשחק. תמיכה בסוגים שונים של מודעות תדרוש מכם להפעיל קבוצות משנה שונות של הגדרות מיקומי מודעות.

הקריאה 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. מייבאים את Ad Placement API

מגדירים את קוד AdSense ומפעילים את מצב הבדיקה

index.html (אינטרנט)

הטמעת המשחק (אופציונלי)

תמיכה באפליקציות לנייד

יישום ראשי (Java)

index.html (אפליקציה)

4. קריאה ל-adConfig()

Game.js

index.html

5. יש להתקשר אל adBreak() כשהמשחק יסתיים

Game.js

השבתה של בדיקות לאפליקציות ייצור

5. יש להתקשר אל `adBreak()` כשהמשחק יסתיים