Menggunakan Ad Placement API

Ad Placement API berisi dua fungsi: adBreak() dan adConfig(), yang ditentukan di namespace global berikut. Sebagian besar argumen adalah fungsi yang Anda berikan yang memungkinkan Anda menangani langkah-langkah utama dalam mempersiapkan 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 subset argumen ini yang berbeda seperti yang dijelaskan di bawah.

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

Fungsi adBreak() menentukan penempatan tempat iklan dapat ditampilkan. Apakah iklan benar-benar ditampilkan atau tidak bergantung pada faktor-faktor seperti berikut:

  • Jenis penempatan iklan yang Anda nyatakan
    • Apakah iklan ini berada di awal pertandingan? Di antara level? Pada saat pemain telah menjeda game?
  • Apakah ada iklan yang sesuai untuk pemain saat ini
    • Apakah iklan ini relevan bagi mereka?
    • Apakah sesuai dengan setelan izin dan privasi datanya?
  • Jumlah iklan yang baru-baru ini dilihat pemutar
  • Setelan kontrol—misalnya, frekuensi iklan yang telah Anda konfigurasi untuk game ini
    • Baik sebagai petunjuk dalam 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. Tempat ini hanya menyatakan tempat iklan dapat ditampilkan.

Hal ini berbeda dengan API tradisional yang kodenya selalu mengetahui apakah iklan tersedia, dan Anda memutuskan dalam game apakah akan menayangkannya atau tidak. Pendekatan ini, yaitu membiarkan Ad Placement API memutuskan apakah iklan ditampilkan di penempatan tertentu atau tidak, adalah pola yang terkadang disebut sebagai "inversi kontrol".

Alasan kami mengalihkan Games API ke model ini adalah pertama, model ini memperpendek kode yang harus Anda tulis dalam game. Kedua, hal ini mempermudah penayangan penempatan yang mematuhi kebijakan dengan pengalaman pengguna yang luar biasa, yang pada gilirannya memungkinkan kami menayangkan beberapa format berperforma terbaik kepada penerbit game. Terakhir, proses penempatan iklan di game Anda dipisahkan dengan lebih jelas 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 Anda, awalnya dengan menentukan petunjuk dalam tag. Namun, pada rilis mendatang, kami akan dapat menyediakan kontrol langsung di frontend AdSense dan AdMob.

Interstisial

Iklan interstisial adalah iklan layar penuh yang dapat ditampilkan pada momen yang berbeda dalam game Anda, seperti saat pemain memulai game, atau setelah pemain menyelesaikan level. Iklan akan menjeda game, menutupi seluruh dokumen, dan pemain dapat memilih untuk mengklik iklan (dalam hal ini, iklan akan ditampilkan di tab browser yang berbeda) atau menutupnya sehingga mereka dapat melanjutkan 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 Anda selalu memberi nama penempatan Anda. Panggilan balik lainnya bersifat opsional.

Urutan panggilan

Tinjau urutan panggilan untuk iklan interstisial.

Diagram urutan panggilan iklan interstisial

Deskripsi

Interstisial – Urutan panggilan mendetail
Game H5 Anda Ad Placement API
  Inisialisasi & pemuatan iklan
Menjalankan game  

Peluang yang baik untuk menampilkan iklan...

adBreak() →

 
 

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

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

return ke API →

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

Catatan

  • adBreak() adalah fungsi asinkron yang langsung ditampilkan.
  • Jika tidak ada iklan yang ditampilkan untuk penempatan, tidak ada callback yang dipanggil—yaitu, tidak ada beforeAd(),afterAd(), yang dipanggil.
  • Untuk memastikan game Anda tidak terus dieksekusi saat iklan ditampilkan, gunakan callback beforeAd() untuk membisukan suara dan menjeda game.
  • beforeAd() bersifat sinkron, Ad Placement API tidak akan menampilkan iklan hingga ditampilkan.
  • Mulai ulang game dan aktifkan kembali suara saat Anda menerima panggilan afterAd() call.
  • Jika disediakan, adBreakDone() selalu dipanggil meskipun iklan tidak ditampilkan di penempatan ini.
  • Panggilan adBreak() saat iklan lain ditampilkan akan gagal dan peringatan akan ditampilkan di konsol JavaScript.

Pre-roll

Preroll adalah iklan interstisial yang ditampilkan sebelum game memuat UI-nya. Ini adalah hal pertama yang dilihat pemain saat membuka game Anda. Karena iklan pra-putar terjadi sangat awal saat halaman dimuat, dan game Anda belum ditampilkan—panggilan biasa untuk menjeda dan membisukan game Anda 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 preroll dilakukan sangat awal saat halaman dimuat. Karena game Anda belum merender UI-nya pada saat ini, Anda tidak boleh meneruskan callback beforeAd() dan afterAd(). Sebagai gantinya, gunakan callback adBreakDone() untuk memulai game setelah penempatan, karena callback ini dijamin akan dipanggil meskipun tidak ada iklan.

Diagram urutan panggilan iklan pre-roll

Memanggil kode berikut di awal logika game akan menempatkan iklan pra-putar. 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 Ad Placement API
  Inisialisasi API & pra-peng-cache-an iklan dimulai
Sedang 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 analitik tambahan).

  

Catatan

  • Pre-roll akan selalu mencoba memuat iklan terlebih dahulu:
    • adConfig(preloadAds: ‘on') tidak diperlukan dengan prerol.
  • Seperti penempatan iklan lainnya, pre-roll dapat menampilkan atau tidak menampilkan iklan.
  • beforeAd() dan afterAd() tidak boleh diteruskan ke preroll.
    • Karena iklan pre-roll berjalan sebelum game Anda dimulai, Anda tidak perlu menjeda atau membisukan suara game.
    • Jika Anda meneruskan beforeAd() atau afterAd() dengan preroll, panggilan akan gagal dan error akan dicatat ke konsol JavaScript.
  • Preroll otomatis menunggu Ad Placement API diinisialisasi dan memuat iklan terlebih dahulu:
    • Namun, ada waktu tunggu (2 detik) yang mencegah panggilan tertunda tanpa batas waktu. Hal ini memastikan bahwa adBreakDone() dipanggil tepat waktu dan game Anda dimulai.
    • adBreakDone() selalu dipanggil meskipun tidak ada iklan.
  • Sebaiknya gunakan iklan pra-putar untuk menempatkan iklan sebelum game Anda dimulai.
    • Atau, Anda dapat menggunakan callback onReady() ke adConfig() sebagai mekanisme untuk mengurutkan logika game dengan inisialisasi API dan memuat iklan terlebih dahulu.

Iklan reward

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

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

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

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

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

Sekali lagi, tujuannya di sini adalah memungkinkan Anda mengintegrasikan game dengan Ad Placement API satu kali, lalu seiring waktu menggunakan kontrol baik di tag, atau di AdSense, Anda dapat mengubah campuran iklan yang diaktifkan secara tepat–tanpa harus mengode ulang dan merilis ulang game.

Jenis penempatan yang diberi reward selalu '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 utama adalah beforeReward() yang merupakan pemicu yang memberi sinyal bahwa Anda harus merender dialog reward, dan adViewed() yang dipanggil saat pemain berhasil melihat iklan, sehingga Anda dapat mengalokasikan reward mereka.

Anda dapat menentukan penempatan iklan 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 dalam game yang menawarkan reward kepada pemain jika mereka menonton 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 Ad Placement API
  Inisialisasi & pra-peng-cache-an 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 merender perintah reward. Hal ini memberi pemain kesempatan untuk mendapatkan reward dengan menonton iklan. Lebih dari satu jenis reward dapat ditawarkan (misalnya, nyawa baru atau koin emas).

Pemain dapat mengklik perintah reward, menutupnya, atau mengabaikannya.

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

Jika tidak, jika perintah reward ditutup atau diabaikan, tidak akan terjadi apa pun hingga Anda melakukan panggilan lain ke adBreak() dengan jenis penempatan reward. Pada saat itu, Ad Placement API akan mereset dan membersihkan status dari panggilan ini. Jika aplikasi memanggil showAdFn dari jeda iklan sebelumnya, tidak ada efeknya.

  

showAdFn() →

 
  ← beforeAd()

Game dijeda, suara dimatikan, dan bersiap menampilkan iklan

return ke API →

 
  API menampilkan iklan. Iklan ini memiliki tombol tutup dan hitung mundur berapa banyak waktu yang tersisa dalam iklan.
JIKA pemutar menutup iklan...
  ← adDismissed()
Pemain menutup iklan dan game tidak memberikan reward.  
ELSE pemutar menonton iklan sampai selesai...
  ← adViewed()
Pemain menonton iklan hingga selesai dan game memberikan reward. (Biasanya dengan menyetel beberapa status game yang kemudian 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 mengaktifkan suara.  
  ← adBreakDone()adBreakDone() selalu dipanggil (meskipun iklan tidak ditampilkan)
Game mencatat analisis tentang penempatan ini.  

Catatan

  • adBreak() adalah fungsi asinkron yang langsung ditampilkan.
  • Jika tidak ada iklan yang ditampilkan untuk penempatan, tidak ada callback yang dipanggil—artinya, tidak ada beforeAd(), beforeReward() yang dipanggil.
  • Untuk memastikan game Anda tidak terus dieksekusi saat iklan ditampilkan, gunakan callback beforeAd() untuk membisukan suara dan menjeda game.
  • beforeAd() bersifat sinkron, Ad Placement API tidak akan menampilkan iklan hingga ditampilkan.
  • Mulai ulang game dan aktifkan kembali suara saat Anda menerima panggilan afterAd() call.
  • Jika disediakan, adBreakDone() selalu dipanggil meskipun iklan tidak ditampilkan di penempatan ini.
  • Panggilan adBreak() saat iklan lain ditampilkan akan gagal dan peringatan akan ditampilkan di konsol JavaScript.