Menggunakan Ad Placement API

Ad Placement API berisi dua fungsi: adBreak() dan adConfig(), yang ditentukan dalam namespace global berikut. Sebagian besar argumen adalah fungsi yang Anda berikan yang memungkinkan Anda menangani langkah-langkah utama untuk menyiapkan dan menampilkan iklan:

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

Fungsi ini digunakan untuk menempatkan dan mengonfigurasi iklan dalam game Anda. Argumen yang ditampilkan di atas adalah satu-satunya argumen valid yang dapat diteruskan ke fungsi ini. Berbagai jenis iklan memerlukan subkumpulan argumen yang berbeda ini seperti yang dijelaskan di bawah.

adBreak() adalah fungsi utama untuk menempatkan iklan dalam game Anda. Ini menentukan penempatan iklan dan mengambil objek yang disebut konfigurasi penempatan yang menentukan semua yang diperlukan untuk menampilkan iklan.

Fungsi adBreak() menentukan penempatan tempat iklan dapat ditampilkan. Benar-benar tampilnya iklan bergantung pada beberapa faktor seperti berikut:

  • Jenis penempatan iklan yang Anda deklarasikan
    • Apakah iklan ini di awal game? Di antara level? Saat pemain menjeda game?
  • Apakah iklan yang cocok ada untuk pemain saat ini
    • Apakah iklan ini relevan bagi mereka?
    • Apakah setelan privasi dan izin data mereka konsisten?
  • Jumlah iklan yang dilihat pemain baru-baru ini
  • Setelan kontrol—misalnya, frekuensi iklan yang telah Anda konfigurasikan untuk game ini
    • Baik sebagai petunjuk di tag, atau,
    • Dalam AdSense—perhatikan bahwa kontrol yang tersedia di AdSense akan berkembang seiring waktu.

Jenis iklan yang ditampilkan juga bergantung pada faktor serupa.

Perhatikan bahwa panggilan ke adBreak() mungkin tidak menampilkan iklan sama sekali. Ini hanya mendeklarasikan tempat iklan dapat ditampilkan.

Ini berbeda dengan API tradisional yang memungkinkan kode Anda selalu mengetahui apakah iklan tersedia, dan Anda memutuskan di dalam game apakah akan menampilkannya atau tidak. Pendekatan untuk membiarkan Ad Placement API memutuskan apakah iklan ditampilkan di penempatan tertentu merupakan pola yang terkadang disebut sebagai "inversi kontrol".

Alasan kami mentransisikan API game ke model ini adalah pertama, karena mempersingkat kode yang harus Anda tulis dalam game. Kedua, ini mempermudah penayangan penempatan yang mematuhi kebijakan dengan pengalaman pengguna yang hebat, yang pada akhirnya memungkinkan kami menayangkan beberapa format berperforma tertinggi kepada penayang game. Terakhir, ini memisahkan proses menempatkan iklan di game dengan lebih baik dari keputusan monetisasi tentang jenis dan jumlah iklan yang akan ditampilkan.

Kami ingin Anda dapat mengubah setelan monetisasi dan mengontrol pengalaman pengguna tanpa harus mengedit dan merilis versi baru game, awalnya dengan menentukan petunjuk di tag. Namun dalam rilis mendatang, kami dapat memberikan kontrol langsung di frontend AdSense dan AdMob.

Interstisial

Iklan interstisial adalah iklan layar penuh yang dapat ditampilkan pada berbagai momen dalam game, seperti saat pemain memulai game, atau setelah pemain menyelesaikan level. Proses ini menjeda game, menutupi seluruh dokumen, dan pemain dapat memilih untuk mengklik iklan (dalam hal ini iklan ditampilkan di tab lain browser) atau menutupnya sehingga iklan dapat dilanjutkan dengan game.

Untuk menempatkan iklan interstisial, isi kolom berikut dalam konfigurasi penempatan:

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

Argumen type diperlukan, dan sebaiknya selalu beri nama penempatan. Callback lainnya bersifat opsional.

Urutan panggilan

Tinjau urutan panggilan untuk iklan interstisial.

Diagram urutan panggilan iklan interstisial

Deskripsi

Interstisial – Urutan panggilan mendetail
Game H5 Anda API Penempatan Iklan
  Inisialisasi & amp; pramuat iklan
Menjalankan game  

Peluang yang bagus untuk menampilkan iklan...

adBreak() →

 
 

Ada iklan yang tersedia dan sekarang adalah waktu yang tepat untuk menampilkannya...

← beforeAd()
Game dijeda, membisukan suara, dan bersiap untuk menampilkan iklan.

return ke API →

 
  Ad Placement API merender iklan interstisial. Pemutar dapat mengklik iklan (yang ditampilkan di tab baru). Mereka harus menutup iklan agar dapat terus bermain game.
  ← afterAd() dipanggil jika iklan telah ditampilkan
Game akan melanjutkan dan membunyikan audio.  
  ← adBreakDone()adBreakDone() selalu dipanggil (meskipun iklan tidak ditampilkan)
Game mencatat analisis tentang penempatan ini.  

Catatan

  • adBreak() adalah fungsi asinkron yang segera ditampilkan.
  • Jika tidak ada iklan yang ditampilkan untuk penempatan, tidak ada callback yang dipanggil, yaitu tidak satu pun dari beforeAd(), afterAd(), yang akan dipanggil.
  • Untuk memastikan game Anda tidak terus dijalankan saat iklan ditampilkan, gunakan callback beforeAd() untuk membisukan suara dan menjeda game.
  • beforeAd() bersifat sinkron, Ad Placement API tidak akan menampilkan iklan sampai ditampilkan.
  • Mulai ulang game dan bunyikan suara saat Anda menerima panggilan afterAd().
  • Jika disediakan, adBreakDone() selalu dipanggil meskipun iklan tidak ditampilkan dalam penempatan ini.
  • Pemanggilan adBreak() saat iklan lain ditampilkan akan gagal dan peringatan akan ditampilkan di konsol JavaScript.

Pre-roll

Preroll adalah interstisial yang ditampilkan sebelum game memuat UI-nya. Hal ini adalah hal pertama yang dilihat pemain saat membuka game Anda. Karena preroll terjadi di awal pemuatan halaman, dan game Anda belum ditampilkan—panggilan biasanya untuk menjeda dan membisukan game tidak diperlukan. Sebagai gantinya, Anda menggunakan callback adBreakDone() untuk mengurutkan awal game dengan iklan—yaitu, merender UI dan mulai memutar suara. Hanya satu preroll yang dapat dipicu untuk setiap pemuatan halaman.

Urutan panggilan

Panggilan untuk pre-roll dilakukan sejak awal pemuatan halaman. Karena game Anda belum merender UI-nya pada tahap ini, Anda tidak boleh meneruskan callback beforeAd() dan afterAd(). Sebagai gantinya, gunakan callback adBreakDone() untuk memulai game Anda setelah penempatan, karena callback ini dijamin akan dipanggil meskipun tidak ada iklan.

Diagram urutan panggilan iklan preroll

Memanggil kode berikut, di awal logika game Anda akan menempatkan iklan preroll. UI Anda tidak boleh dirender sebelum kode ini dipanggil.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
Preroll – Urutan panggilan mendetail
Game H5 Anda API Penempatan Iklan
  Inisialisasi API & amp; caching awal iklan dimulai
Berjalan, tetapi belum dimulai dan belum menampilkan UI  

adBreak(type:'preroll',…) →

 
 

Ad Placement API selesai melakukan inisialisasi dan memuat iklan. Jika ada iklan, iklan tersebut akan ditampilkan. Pemutar dapat mengklik iklan (yang ditampilkan di tab baru). Mereka harus menutupnya agar game dapat dimulai.

 

← adBreakDone() selalu dipanggil (meskipun iklan tidak ditampilkan)

UI game dirender ke layar dan pemain kini dapat berinteraksi dengannya. Game dapat menggunakan objek placementInfo yang diteruskan ke adBreakDone() sesuai kebutuhan (misalnya, untuk mencatat analisis tambahan ke dalam log).

  

Catatan

  • Preroll akan selalu berupaya melakukan pramuat iklan:
    • Tidak perlu memanggil adConfig(preloadAds: ‘on') dengan preroll.
  • Seperti penempatan iklan lainnya, preroll dapat menampilkan iklan atau tidak.
  • beforeAd() dan afterAd() tidak boleh diteruskan ke preroll.
    • Karena iklan preroll berjalan sebelum game dimulai, Anda tidak perlu menjeda atau menonaktifkan suara game.
    • Jika Anda meneruskan beforeAd() atau afterAd() dengan preroll, panggilan akan gagal dan error akan dicatat ke dalam konsol JavaScript.
  • Preroll otomatis menunggu Ad Placement API untuk melakukan inisialisasi dan memuat iklan di awal:
    • Namun, ada waktu tunggu (2 dtk) yang mencegah panggilan ditunda tanpa batas waktu. Hal ini memastikan bahwa adBreakDone() dipanggil dengan mode yang tepat waktu dan game Anda dimulai.
    • adBreakDone() selalu dipanggil meskipun tidak ada iklan.
  • Sebaiknya gunakan pre-roll untuk menempatkan iklan sebelum game dimulai.
    • Atau, Anda dapat menggunakan callback onReady() ke adConfig() sebagai mekanisme untuk mengurutkan logika game dengan inisialisasi API dan memuat iklan di awal.

Iklan reward

Iklan reward memungkinkan Anda memberikan reward kepada pemain berupa item dalam aplikasi jika mereka memilih untuk menonton iklan. Sementara interstisial dikecualikan, pemain akan melihat iklan dan dapat memilih untuk menutupnya. Iklan reward bersifat keikutsertaan. Pemain memilih apakah dan kapan mereka ingin menonton iklan untuk menerima reward.

Tidak seperti interstisial, di mana pemain dapat menutup iklan kapan saja, untuk menerima reward, mereka harus melihat iklan selama durasi minimum (yang dapat bervariasi bergantung pada materi iklan yang ditampilkan).

Karena iklan reward bersifat opsional untuk pemain, iklan ini memerlukan integrasi yang lebih dalam dalam alur game Anda. Anda harus menyediakan fungsi untuk merender perintah reward dalam game, dan untuk mengalokasikan reward kepada pemain jika mereka menonton iklan.

Reward tidak boleh memiliki nilai di luar aplikasi, tidak boleh memiliki (atau mudah ditukar dengan) nilai uang, dan tidak boleh dijual atau ditukar dengan barang dan layanan, dan Anda tidak boleh mendorong pemain untuk mengklik iklan. Harap buka draf kebijakan untuk interstisial dan reward untuk detail selengkapnya.

Karena reward bersifat opsional untuk pemain, Anda dapat menambahkannya di mana saja yang masuk akal dalam game dan dapat menggunakannya selain interstisial. Seperti interstisial, penempatan ini adalah peluang untuk menampilkan iklan reward. Ad Placement API hanya akan memanggil kode Anda jika iklan reward sebenarnya akan ditawarkan pada titik tertentu dalam game.

Sekali lagi, sasaran di sini adalah memungkinkan Anda mengintegrasikan game dengan Ad Deployment API, lalu, seiring waktu menggunakan kontrol baik dalam tag atau di AdSense, Anda dapat mengubah campuran iklan yang diaktifkan secara tepat, tanpa harus melakukan recode dan merilis ulang game.

Jenis penempatan reward selalu berupa 'reward' dan semua kolom dalam konfigurasi penempatan dapat digunakan.

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

Fungsi baru yang penting adalah beforeReward() yang merupakan pemicu yang menandakan bahwa Anda harus merender perintah reward, dan adViewed() yang dipanggil saat pemain berhasil melihat iklan, sehingga Anda dapat mengalokasikan reward.

Anda dapat menentukan penempatan reward sebagai berikut:

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

Iklan reward dimulai dengan perintah di game Anda yang menawarkan reward kepada pemain jika mereka melihat iklan.

Contoh perintah iklan: Tonton video untuk mendapatkan nyawa tambahan

Urutan panggilan untuk iklan reward

Diagram urutan panggilan reward

Deskripsi

Iklan reward – Urutan panggilan mendetail
Game H5 Anda API Penempatan Iklan
  Inisialisasi & amp; pra-caching iklan
Menjalankan game  

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

 
 

Ada iklan yang tersedia, jadi mulai penempatan iklan reward. beforeReward() dipanggil secara sinkron–segera setelah panggilan ke adBreak()

← beforeReward(showAdFn)

Game akan merender perintah reward. Dengan begitu, pemain dapat memperoleh reward dengan menonton iklan. Lebih dari satu jenis reward dapat ditawarkan (misalnya, nyawa baru atau koin emas).

Pemain dapat mengklik permintaan reward, menutupnya, atau mengabaikannya.

Jika pengguna mengklik perintah, game akan menyimpan jenis reward yang diminta dan memanggil showAdFn()...

Atau, jika permintaan reward ditutup atau diabaikan, tidak akan ada yang terjadi hingga Anda melakukan panggilan lain ke adBreak() dengan jenis penempatan reward. Pada tahap ini, Ad Placement API akan direset dan membersihkan status dari panggilan ini. Jika aplikasi memanggil showAdFn dari jeda iklan sebelumnya, aplikasi tidak akan berpengaruh.

  

showAdFn() →

 
  ← beforeAd()

Game dijeda, membisukan suara, dan bersiap untuk menampilkan iklan

return ke API →

 
  API menampilkan iklan. Iklan ini memiliki tombol tutup dan hitung mundur jumlah waktu yang tersisa di iklan.
Jika pemutar menutup iklan...
  ← adDismissed()
Pemain menutup iklan dan game tidak memberikan reward.  
ATAU pemain menonton iklan hingga selesai...
  ← adViewed()
Pemain menonton iklan hingga selesai dan game memberikan reward. (Biasanya dengan menyetel beberapa status game yang akan diambil saat game dimulai ulang dengan panggilan ke afterAd() di bawah).  
Setelah iklan ditonton atau ditutup...
  ← afterAd() dipanggil jika iklan telah ditampilkan
Game akan melanjutkan dan membunyikan audio.  
  ← adBreakDone()adBreakDone() selalu dipanggil (meskipun iklan tidak ditampilkan)
Game mencatat analisis tentang penempatan ini.  

Catatan

  • adBreak() adalah fungsi asinkron yang segera ditampilkan.
  • Jika tidak ada iklan yang ditampilkan untuk penempatan, tidak ada callback yang dipanggil—yaitu, tidak satu pun dari beforeAd(), beforeReward() yang akan dipanggil.
  • Untuk memastikan game Anda tidak terus dijalankan saat iklan ditampilkan, gunakan callback beforeAd() untuk membisukan suara dan menjeda game.
  • beforeAd() bersifat sinkron, Ad Placement API tidak akan menampilkan iklan sampai ditampilkan.
  • Mulai ulang game dan bunyikan suara saat Anda menerima panggilan afterAd().
  • Jika disediakan, adBreakDone() selalu dipanggil meskipun iklan tidak ditampilkan dalam penempatan ini.
  • Pemanggilan adBreak() saat iklan lain ditampilkan akan gagal dan peringatan akan ditampilkan di konsol JavaScript.