Ad Placement API'yi kullanma

Ad Placement API iki işlev içerir: Aşağıdaki genel ad alanında tanımlanan adBreak() ve adConfig(). Bağımsız değişkenlerin çoğu, bir reklamı hazırlamak ve görüntülemek için gereken temel adımları işlemenizi sağlayan işlevlerdir:

adBreak({
   type: '<type>',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and un-mute the sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before completion
   adViewed: () => {},                  // Ad was viewed and closed
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

adConfig({
   preloadAdBreaks: 'on|auto',      // Should ads always be preloaded
   sound: 'on|off',                 // Is sound currently enabled within the game
});

Bu işlevler, oyununuza reklam yerleştirmek ve reklamları yapılandırmak için kullanılır. Yukarıda gösterilen bağımsız değişkenler, bu işlevlere aktarılabilecek tek geçerli bağımsız değişkendir. Farklı reklam türleri, aşağıda açıklandığı gibi bu bağımsız değişkenlerin farklı alt kümelerini gerektirir.

adBreak(), oyunun içine reklam yerleştirmenin temel işlevidir. Bir reklam yerleşimini tanımlar ve bir reklam göstermek için gereken her şeyi belirten yerleşim yapılandırması adlı bir nesne alır.

adBreak() işlevi, reklamın gösterilebileceği bir yerleşimi tanımlar. Bir reklamın gerçekten gösterilip gösterilmeyeceği aşağıdakiler gibi faktörlere bağlıdır:

  • Beyan ettiğiniz reklam yerleşiminin türü
    • Bu reklam oyunun başında mı? Seviyeler arasında mı? Oyuncu oyunu duraklattığında mı?
  • Mevcut oyuncu için uygun bir reklam olup olmadığı
    • Bu reklam onlarla alakalı mı?
    • Veri gizliliği ve izin ayarlarına uygun mu?
  • Oyuncunun yakın zamanda gördüğü reklam sayısı
  • Kontrol ayarları (ör. bu oyun için yapılandırdığınız reklam sıklığı)
    • Etikette ipuçları olarak veya
    • AdSense'te, AdSense'teki kontrollerin zaman içinde değişeceğini unutmayın.

Gösterilen reklamın türü de benzer faktörlere bağlıdır.

adBreak() çağrısının hiç reklam göstermeyebileceğini unutmayın. Yalnızca bir reklamın gösterilebileceği bir yeri belirtir.

Bu, kodunuzun bir reklamın kullanılabilir olup olmadığını her zaman bildiği ve oyunun gösterilip gösterilmeyeceğine sizin karar verdiğiniz geleneksel API'lerden farklıdır. Reklam Yerleşimi API'sini kullanmaya yönelik bu yaklaşım, bir reklamın belirli bir yerleşimde gösterilip gösterilmeyeceğine karar verir. Bu kalıp, bazen "kontrolü tersine çevirme" olarak adlandırılır.

Games API'mizi bu modele taşımamızın nedeni, ilk olarak oyununuzda yazmanız gereken kodu kısaltmaktır. İkinci olarak, mükemmel kullanıcı deneyimine sahip, politikaya uygun yerleşimler sunmayı kolaylaştırır. Bu da en yüksek performanslı biçimlerimizden bazılarını oyun yayıncılarına sunmamıza olanak tanır. Son olarak, oyuna reklam yerleştirme sürecini, gösterilecek reklam türü ve sayısıyla ilgili para kazanma kararlarından daha net bir şekilde ayırır.

Başlangıçta etikette ipuçları belirterek, oyununuzun yeni bir sürümünü düzenleyip yayınlamak zorunda kalmadan para kazanma ayarlarınızı değiştirebilmenizi ve kullanıcı deneyimini kontrol edebilmenizi istiyoruz. Ancak daha sonraki sürümlerde, kontrolleri doğrudan AdSense ve AdMob ön uçlarında sağlayacağız.

Geçiş Reklamları

Geçiş reklamları, oyununuzun farklı anlarında (ör. oyuncu oyunu başlatırken veya oyuncu bir seviyeyi tamamladıktan sonra) gösterilebilen tam ekran reklamdır. Oyunu duraklatır, dokümanın tamamını kaplar ve oynatıcı reklamı tıklamayı (bu durumda tarayıcı farklı bir sekmede gösterilir) veya kapatmaya karar vererek oyuna devam edebilir.

Bir geçiş reklamı yerleştirmek için yerleşim yapılandırmasında aşağıdaki alanları doldurun:

adBreak({
   type: 'start',           // The type of this placement
   name: 'game_started',    // A descriptive name for this placement
   beforeAd: beforeAd,      // Prepare for the ad. Mute and pause the game flow
   afterAd: afterAd,        // Resume the game and un-mute the sound
   adBreakDone: breakDone,  // Always called (if provided) even if an ad didn't show
});

type bağımsız değişkeni gereklidir ve yerleşimlerinizi her zaman adlandırmanızı öneririz. Diğer geri çağırmalar isteğe bağlıdır.

Arama dizisi

Geçiş reklamının çağrı dizisini inceleyin.

Geçiş reklamı çağrı dizisi diyagramı

Açıklama

Geçiş reklamı - Ayrıntılı arama dizisi
H5 Oyununuz Reklam Yerleşimi API'si
  Reklamları başlatma ve önceden yükleme
Oyun çalışıyor  

Reklam göstermek için iyi bir fırsat...

adBreak() →

 
 

Bir reklam var ve şimdi bunu göstermenin tam zamanı...

← beforeAd()
Oyun duraklatılır, sesi kapatır ve reklamı göstermeye hazır hâle gelir.

API'ye return →

 
  Ad Placement API, geçiş reklamını oluşturur. Oynatıcı reklamı tıklayabilir (yeni sekmede gösterilir). Oyunu oynamaya devam etmek için reklamı kapatmaları gerekir.
  Reklam gösteriliyorsa ← afterAd() çağrılır
Oyunun duraklatması kaldırılır ve ses açılır.  
  ← adBreakDone()adBreakDone() her zaman çağrılır (reklam gösterilmemiş olsa bile)
Oyun bu yerleşimle ilgili analizleri günlüğe kaydeder.  

Notlar

  • adBreak() hemen dönen eşzamansız bir işlevdir.
  • Bir yerleşim için görüntülenecek reklam yoksa geri çağırmaların hiçbiri çağrılmaz, yani beforeAd(),afterAd() öğesinin hiçbiri çağrılmaz.
  • Reklam oynatılırken oyununuzun yürütülmeye devam etmesini önlemek için beforeAd() geri çağırmasını kullanarak sesi kapatıp oyunu duraklatın.
  • beforeAd() eşzamanlıdır, Ad Placement API, geri dönene kadar bir reklam göstermez.
  • Oyununuzu yeniden başlatın ve afterAd() aramasını aldığınızda sesi açın.
  • Bu yerleşimde bir reklam gösterilmemiş olsa bile adBreakDone() her zaman çağrılır.
  • Başka bir reklam gösterilirken adBreak() işlevi çağrılamaz ve JavaScript konsolunda bir uyarı görüntülenir.

Videodan önce gösterilen reklamlar

Videodan önce gösterilen reklam, oyununuz kullanıcı arayüzünü yüklemeden önce gösterilen bir geçiş reklamıdır. Bu, bir oyuncunun oyununuza gittiğinde gördüğü ilk şeydir. Videodan önce gösterilen reklamlar sayfa yüklemenin başlarında gerçekleşir ve oyununuz henüz gösterilmez. Bu nedenle, oyununuzu duraklatmak ve yoksaymak için her zamanki bir çağrı yapmanız gerekmez. Bunun yerine, adBreakDone() ile geri çağırmayı kullanarak oyununuzun başlangıcını reklamla (yani kullanıcı arayüzünü oluşturup ses çalmaya) sıralayabilirsiniz. Her bir sayfa yükleme için yalnızca bir tane videodan önce gösterilen reklam tetiklenebilir.

Arama dizisi

Videodan önce gösterilen reklam çağrısı, sayfa yüklenmenin çok erken bir aşamasında yapılır. Oyununuz bu aşamada kullanıcı arayüzünü oluşturmadığı için beforeAd() ve afterAd() geri çağırmalarını iletmemeniz gerekiyor. Bunun yerine, yerleşimden sonra oyununuzu başlatmak için adBreakDone() geri çağırmasını kullanın. Reklam olmadan bile çağrılabileceği garanti edilir.

Videodan önce gösterilen reklam çağrısı dizi şeması

Oyun mantığınızın başında aşağıdaki kodu çağırdığınızda videodan önce gösterilen reklam yerleştirilir. Bu kod çağrılmadan önce kullanıcı arayüzünüz oluşturulmamalıdır.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
Videodan önce gösterilen reklam – Ayrıntılı arama dizisi
H5 Oyununuz Reklam Yerleşimi API'si
  Reklamları başlatma ve reklamları önceden önbelleğe alma işlemleri başlar
Çalışıyor ancak başlatılmadı ve bir kullanıcı arayüzü göstermedi  

adBreak(type:'preroll',…) →

 
 

Ad Placement API, reklamları ilk kullanıma hazırlama ve yükleme işlemini tamamlar. Reklam varsa bu reklam gösterilir. Oynatıcı reklamı tıklayabilir (yeni bir sekmede gösterilir). Oyunun başlayabilmesi için oyunu kapatmaları gerekir.

 

← adBreakDone() her zaman çağrılır (reklam gösterilmese bile)

Oyun kullanıcı arayüzü ekranda oluşturulur ve oyuncu artık bu etkileşimle etkileşim kurabilir. Oyun, gerektiğinde adBreakDone() ürününe iletilen placementInfo nesnesini kullanabilir (örneğin, ek analizleri günlüğe kaydetmek için).

  

Notlar

  • Videodan önce gösterilen reklamlar her zaman reklamları önceden yüklemeyi dener:
    • Videodan önce gösterilen reklamlarda adConfig(preloadAds: ‘on') yönteminin aranması gerekmez.
  • Diğer reklam yerleşimlerinde olduğu gibi, videodan önce gösterilen reklam da reklam gösterebilir veya göstermeyebilir.
  • beforeAd() ve afterAd(), bir videodan önce gösterilen reklama geçmemelidir.
    • Videodan önce gösterilen reklamlar, oyununuz başlamadan önce yayınlandığından oyun sesini duraklatmanız veya sesini kapatmanız gerekmez.
    • Videodan önce gösterilen reklamla beforeAd() veya afterAd() ilettiğinizde arama başarısız olur ve JavaScript konsoluna bir hata kaydedilir.
  • Videodan önce gösterilen reklamlar, Ad Placement API'nin reklamları ilk kullanıma hazırlamasını ve önceden yüklemesini bekler:
    • Ancak, aramanın süresiz olarak geciktirilmesini engelleyen bir zaman aşımı (2) vardır. Bu, adBreakDone() adlı oyuncunun zamanında başlatılmasını ve oyununuzun başlamasını sağlar.
    • Reklam olmadığında bile adBreakDone() her zaman çağrılır.
  • Oyun başlamadan önce reklam yerleştirmek için videodan önce gösterilen reklam kullanmanızı öneririz.
    • Alternatif olarak, API'nin ilk kullanıma hazırlanması ve reklamların önceden yüklenmesiyle oyun mantığınızı sıralama mekanizması olarak adConfig() için onReady() geri çağırmasını kullanabilirsiniz.

Ödüllü reklamlar

Ödüllü reklam sayesinde, reklam izlemeyi tercih eden oyuncuları uygulama içi öğelerle ödüllendirebilirsiniz. Geçiş reklamları devre dışı bırakıldığında, reklama bir oynatıcı gösterilir ve oynatıcıyı kapatabilir. Ödüllü reklamlar etkinleştirilir. Oyuncu, ödül kazanmak için bir reklamı izlemek isteyip istemeyeceğini ve ne zaman izlemek istediğini seçer.

Oyuncunun reklamı istediği zaman kapatabileceği geçiş reklamlarından farklı olarak, ödül kazanmak için reklamı minimum süre boyunca görüntülemesi gerekir (gösterilen reklam öğesine bağlı olarak değişebilir).

Ödüllü reklamlar oyuncu için isteğe bağlı olduğundan oyun akışınıza daha kapsamlı şekilde entegre edilmelidir. Oyununuzda ödül isteği oluşturacak işlevler sağlamanız ve reklamı izleyen oyuncuya ödülü vermeniz gerekir.

Ödüller, uygulamanız dışında bir değere sahip olmamalıdır. Parasal değer taşımamalıdır (veya kolayca takas edilemez), ayrıca ürün ve hizmetler için satılabilir veya takas edilemez. Ayrıca kullanıcıları reklamları tıklamaya teşvik etmemelisiniz. Daha fazla bilgi için lütfen geçiş reklamlarına yönelik ödüllü reklam politikasını ve ödüllü reklamları inceleyin.

Ödüller, oyuncu için isteğe bağlı olduğundan bunları oyun içinde anlamlı olan ve geçiş reklamlarına ek olarak herhangi bir yere ekleyebilirsiniz. Geçiş reklamlarında olduğu gibi bu yerleşimler de ödüllü reklam gösterme fırsatlarıdır. Ad Placement API, yalnızca oyununuzun belirli bir noktasında ödüllü reklam gerçekten sunulacaksa kodunuzu çağırır.

Buradaki hedef, oyununuzu Reklam Yerleşimi API'siyle bir kez entegre etmenize olanak tanımaktır. Ardından zaman içinde etiketteki veya AdSense'teki kontrolleri kullanarak oyununuzu yeniden kodlamak ve tekrar yayınlamak zorunda kalmadan, etkinleştirilen reklamların tam karışımını değiştirebilirsiniz.

Ödüllü bir yerleşimin türü her zaman 'reward''dir ve yerleşim yapılandırmasındaki tüm alanlar kullanılabilir.

adBreak({
   type: 'reward',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and re-enable sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before it finished.
   adViewed: () => {},                  // Player watched the ad–give them the reward.
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

Bu yeni temel işlevler, ödül istemini oluşturmanız gerektiğini işaret eden tetikleyici olan beforeReward() ve oyuncu reklamı başarıyla görüntülediğinde çağrılan adViewed() öğesidir. Böylece ödülünü ayırabilirsiniz.

Ödüllü yerleşimi şu şekilde tanımlayabilirsiniz:

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

Ödüllü reklamlar, oyununuzdaki bir istemle başlar. Kullanıcı bir reklamı görüntülediğinde ödül kazanır.

Örnek reklam istemi: Ek can almak için video izleyin

Ödüllü reklam için arama dizisi

Ödüllü arama dizisi şeması

Açıklama

Ödüllü reklam – Ayrıntılı arama dizisi
H5 Oyununuz Reklam Yerleşimi API'si
  Reklamları başlatma ve önbelleğe alma
Oyun çalışıyor  

adBreak(type:'reward', ... ) →

 
 

Bir reklam bulunduğundan ödüllü reklam yerleşimi başlatın. beforeReward(), adBreak() çağrısından hemen sonra eşzamanlı olarak çağrılır

← beforeReward(showAdFn)

Oyun, ödül istemini oluşturur. Bu, oyuncuya reklam izleyerek ödül kazanma fırsatı sunar. Birden fazla ödül türü sunulabilir (örneğin, yeni bir yaşam veya altın para).

Oyuncu, bir ödül istemini tıklayabilir, reddedebilir veya yoksayabilir.

Bir istemi tıklamaları halinde oyun, istedikleri ödül türünü depolar ve showAdFn()... numaralı telefonu arar

Aksi takdirde, ödül istemi reddedilir veya yoksayılırsa ödül yerleşim türüyle adBreak() çağrısına tekrar başlayana kadar hiçbir şey gerçekleşmez. Bu aşamada Reklam Yerleşimi API'si sıfırlanır ve görüşmeden itibaren durum temizlenir. Uygulama, önceki bir reklam arasından showAdFn öğesini çağırırsa bunun herhangi bir etkisi olmaz.

  

showAdFn() →

 
  ← beforeAd()

Oyun duraklatılır, sesi kapatır ve reklam göstermeye hazır hale gelir

API'ye return →

 
  API, reklamı gösterir. Kapat düğmesi ve reklamda ne kadar süre kaldığını gösteren bir geri sayım içerir.
Oynatıcı reklamı kapatırsa...
  ← adDismissed()
Oyuncu reklamı kapattı ve oyun ödül vermedi.  
Oynatıcı daha sonra reklamı sonuna kadar izler...
  ← adViewed()
Oyuncu reklamı sonuna kadar izledi ve oyun ödül verdi. (Buna genellikle oyun durumu yeniden ayarlanır. Oyun durumu, aşağıdaki afterAd() çağrısıyla yeniden başlatıldığında alınır.)  
Reklam izlendikten veya kapatıldıktan sonra...
  ← Bir reklam gösterildiği takdirde afterAd() çağrılır
Oyunun duraklatması kaldırılır ve ses açılır.  
  ← adBreakDone()adBreakDone() her zaman çağrılır (reklam gösterilmemiş olsa bile)
Oyun bu yerleşimle ilgili analizleri günlüğe kaydeder.  

Notlar

  • adBreak() hemen dönen eşzamansız bir işlevdir.
  • Bir yerleşim için görüntülenecek reklam yoksa geri çağırmaların hiçbiri çağrılmaz, yani beforeAd() ve beforeReward() hiçbiri çağrılmaz.
  • Reklam oynatılırken oyununuzun yürütülmeye devam etmesini önlemek için beforeAd() geri çağırmasını kullanarak sesi kapatıp oyunu duraklatın.
  • beforeAd() eşzamanlıdır, Ad Placement API, geri dönene kadar bir reklam göstermez.
  • Oyununuzu yeniden başlatın ve afterAd() aramasını aldığınızda sesi açın.
  • Bu yerleşimde bir reklam gösterilmemiş olsa bile adBreakDone() her zaman çağrılır.
  • Başka bir reklam gösterilirken adBreak() işlevi çağrılamaz ve JavaScript konsolunda bir uyarı görüntülenir.