Bu sayfa, Cloud Translation API ile çevrilmiştir.

Örnek uygulama

Ad Placement API, web'deki veya uygulamalardaki HTML5 oyunlarında geçiş reklamları ve ödüllü reklamlar kullanan AdSense ve AdMob geliştiricilerini desteklemek için tasarlanmıştır. Bu örnekte, Ad Placement API'nin bir oyuna nasıl entegre edileceği ve geçiş reklamı yerleştirmek için nasıl kullanılacağı gösterilmektedir.

Ön koşullar

Başlamadan önce aşağıdakilere ihtiyacınız olacaktır:

Aynı dizinde iki boş dosya oluşturun:
- index.html
- oyun.js
Python'u yerel olarak yükleyin veya uygulamanızı test etmek için bir web sunucusu kullanın

Uygulama örnek kodu

AdMob yayıncıları, API'nin uygulama oyunlarına nasıl entegre edilebileceğini daha iyi anlamak için örnek uygulama kodu indirebilir.

Uygulama örnek kodunu indirme

1. Geliştirme sunucusu başlatma

Ads Yerleşim API'sı, bağımlılıkları yüklendiği sayfayla aynı protokol aracılığıyla yüklediğinden, uygulamanızı test etmek için bir web sunucusu kullanmanız gerekir. Yerel bir geliştirme ortamı oluşturmak için Python'un yerleşik sunucusunu kullanabilirsiniz.

Terminali açın.
index.html dosyanızı içeren dizine gidip şunu çalıştırın:
```
python -m http.server 8000
```
Not: http.server yalnızca Python 3.x sürümünde kullanılabilir.
Bir web tarayıcısında localhost:8000 adresine gidin

Apache HTTP Server gibi başka bir web sunucusu da kullanabilirsiniz.

2. HTML5 oyunu oluştur

HTML5 tuval öğesi ve oyunu tetiklemeyi sağlayan bir düğme oluşturmak için index.html özelliğini değiştirin. Ardından game.js dosyasını yüklemek için gerekli komut dosyası etiketini ekleyin.

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>

"Oynat" düğmesi tıklandığında game-js'yi madeni para çevirme oyunu oynamak için değiştirin.

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

Bu adımı tamamladıktan sonra tarayıcınızda (geliştirme sunucunuz aracılığıyla) index.html uygulamasını açtığınızda, oyun tuvalini ve &"Oyun" düğmesini görebilmeniz gerekir. Oynat'ı tıklarsanız jeton çevirme oyunu başlar.

3. Reklam Yerleşimi API'sini içe aktarın

Daha sonra, game.js etiketinden önce index.html bölümüne bir komut dosyası etiketi ekleyerek Ad Placement API'yi oyununuza ekleyin.

Komut dosyası etiketi birkaç parametre alabilir. AdSense mülk kodunu belirtmek ve test modunu etkinleştirmek için aşağıdaki parametreleri kullanacağız:

data-ad-client=<AdSense property code> AdSense mülk kodunuz. Bu, uygulamalarda çalışacak oyunlar için bile gereklidir.
data-adbreak-test="on" Test modunu etkinleştirir. Oyunculara sunulan oyunlar için bunu kaldırın.

AdSense Kodunu ayarlayın ve test modunu etkinleştirin

Ad Placement API işlevi AdSense koduna eklenir. Bu özelliği etkinleştirmek için önce AdSense kodunu eklemeniz ve iki temel işlevini başlatan küçük bir komut dosyası snippet'i eklemeniz gerekir: adBreak() ve 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>

Oyununuzu yerleştirme (isteğe bağlı)

Bir oyunu iFrame içindeki diğer sayfalara yerleştirmek istiyorsanız ve adsbygoogle etiketi oyunun HTML sayfasındaysa allow='autoplay' öğesine iframe öğesi eklediğinizden emin olun. Bu en iyi uygulamalardan biridir ve bazı reklamların oyununuza uygun olması için gereklidir.

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

Mobil uygulamaları destekleme

H5 oyunları normal web tarayıcılarında veya uygulama içindeki Web Görünümü ya da Chrome Özel Sekmesinde çalışabilir. Ad Placement API, oyununuzun hangi ortamda çalıştığını algılayıp reklam isteklerini uygun şekilde yönlendirebilir. Oyununuz normal bir web tarayıcısı içinde çalışıyorsa reklam istekleri normal AdSense istekleri olarak değerlendirilir. Ad Placement API bir uygulama içi ortam algılarsa AdMob reklamları istemek ve göstermek için GMA SDK'sı (varsa) ile iletişim kurar.

Bu özellik şu anda, AdMob GMA SDK'sı ile bağlantılı olan Android uygulamalarında desteklenmektedir. Etkinleştirmek için oyununuzu GMA SDK'sıyla gösterecek Web Görünümü'nü kaydetmeniz, ardından AdMob reklam birimlerini yapılandırıp bunları AdSense etiketine ek parametreler olarak iletmeniz gerekir. Oyununuz uygun bir uygulama içinde yayınlandığında Ad Placement API, reklam göstermek için bu reklam birimlerini kullanır.

Mobil desteği etkinleştirmek için aşağıdaki ek etiket parametrelerini belirtmeniz gerekir:

data-admob-interstitial-slot=<AdMob slot ID> Daha önce yapılandırdığınız bir AdMob geçiş reklamı birim kimliği.
data-admob-rewarded-slot=<AdMob slot ID> AdMob ödüllü reklam birimi kimliği.

AdSense mülk kodunuz her zaman data-ad-client parametresiyle iletilmelidir. En az bir data-admob-interstitial-slot veya data-admob-rewarded-slot belirtilmelidir. Oyununuzda her iki biçim de kullanılıyorsa her iki parametre de belirtilmelidir.

İsteğe bağlı olarak, oyunun AdMob isteklerini desteklemeyen bir ortamda (ör. AdMob GMA SDK'sı yapılandırılmamış uygulama dışı ortamlar veya uygulamalar) oynandığı durumlarda, oyununuzun yalnızca AdMob'dan reklam göstermesi ve AdSense'e yedek getirmemesi gerektiğini belirtmek için data-admob-ads-only=on etiket parametresini de belirtebilirsiniz.

Önemli: Oyununuzu bir uygulamaya yerleştirilecek şekilde tasarlarken, uygulamanın sahibi sizseniz veya uygulamanın sahibiyle gelir paylaşımı sözleşmesi imzalıyorsanız bunu yüksek performans gösteren ve politikaya uygun bir şekilde gerçekleştirmenin tek yolu bu AdMob desteğini kullanmaktır.

Öncelikle, oyununuzu GMA SDK'sıyla gösterecek Web Görünümü'nü kaydedin:

MainActivity.java (uygulama)

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

Ardından, AdMob reklam birimlerini (biri geçiş reklamları, diğeri ödüllü reklamlar için) aşağıdaki gibi iletin:

index.html (uygulama)

 [...]
    <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() çağrısı yapın

adConfig() çağrısı, oyunun mevcut yapılandırmasını Ad Placement API'ye iletir. API, daha sonra bu bilgileri kullanarak istediği reklam türlerini oyuna uygun olacak şekilde filtreleyebilir (ses özelliği etkinse ses gerektiren video reklamlar gibi).

Bu yapılandırma değişikliği olduğunda (örneğin, kullanıcının sesi kapatması veya sesinin açılması) adConfig() numarasına çağrı yapılmalıdır. Oyunun üreticisinde adConfig() adlı kişiyi aradıktan sonra başka bir adConfig() çağrısı yapan oyunun sesini kapatıp açmak için bir düğme ekleyin.

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

Şimdi sesi kapatma düğmesini HTML dosyanıza ekleyin.

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. Oyun sona erdiğinde `adBreak()` numaralı telefonu arayın

adBreak() çağrısı bir reklam yerleşimini tanımlar ve oyununuzda bu noktada bir reklamı göstermek için gereken her şeyi belirten yerleşim yapılandırması adlı nesneyi alır. Farklı reklam türlerini desteklemek, farklı bir yerleşim yapılandırması alt kümesi başlatmanızı gerektirir.

adBreak() çağrısı, bir reklamın gösterilebileceği yerleşimi, bir başka deyişle reklam gösterme fırsatını tanımlar. Bir reklamın gerçekten gösterilip gösterilmeyeceği, birkaç unsura bağlıdır:

Belirttiğiniz reklam yerleşiminin türü.
Bu reklam yerleşiminden önce uygun kullanıcı etkileşimleri olup olmadığı.
Mevcut oynatıcı için uygun bir reklam olup olmaması durumunda:
- Alaka düzeyi yüksek.
- Bu kullanıcıların veri gizliliği ve izin ayarları tutarlıdır.
Kullanıcının yakın zamanda gördüğü reklam sayısı.
Bu oyun için yapılandırdığınız kontrol ayarları:
- Etiketteki ipuçları.
- AdSense'te (Not: AdSense'teki kontroller zamanla değişecektir)

Oyun yeniden başlatıldığında gösterilecek bir geçiş reklamı için kod ekleyin: play() işlevi içinde, yalnızca oyun bir kez oynandıktan sonra çalıştırılan adBreak() işlevine çağrı yapın.

adBreak(), "Oynat" düğmesini tıklama gibi bir kullanıcı işlemi kapsamında çağrılmalıdır. Aksi takdirde API, reklam isteğinde bulunamaz ve reklam görüntüleyemez.

Reklam arasından önce ve sonra çağrılacak işlevler oluşturun. Bunları daha sonra adBreak() yerleşim yapılandırmasında kullanacaksınız. beforeAd ve afterAd işlevlerinin yalnızca uygun bir reklam bulunması durumunda çağrılacağını unutmamak önemlidir.

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

Yazı tura uygulaması artık reklamların gösterilmesi için reklam yerleşimleri oluşturuyor.

Kendi uygulamanızda, oyun sona erdiğinde reklamlar için uygun olmayan başka yerler de olabilir. Bu yerlerden adBreak() arandığında örnektekine benzer olacaktır.

Üretim uygulamaları için testi kapat

Bu kod üretim sırasında test ayarlarını etkinleştirdiği için, uygulamanızı yayınlamadan önce index.html içindeki data-adbreak-test="on" satırını kaldırmanız veya açıklamanız önemlidir.

Örnek uygulama

Ön koşullar

Uygulama örnek kodu

1. Geliştirme sunucusu başlatma

2. HTML5 oyunu oluştur

index.html

oyun.js

3. Reklam Yerleşimi API'sini içe aktarın

AdSense Kodunu ayarlayın ve test modunu etkinleştirin

index.html (web)

Oyununuzu yerleştirme (isteğe bağlı)

Mobil uygulamaları destekleme

MainActivity.java (uygulama)

index.html (uygulama)

4. adConfig() çağrısı yapın

oyun.js

index.html

5. Oyun sona erdiğinde adBreak() numaralı telefonu arayın

oyun.js

Üretim uygulamaları için testi kapat

5. Oyun sona erdiğinde `adBreak()` numaralı telefonu arayın