ใช้ Ad Placement API

Ad Placement API มี 2 ฟังก์ชัน ได้แก่ adBreak() และ adConfig() ที่กําหนดไว้ในเนมสเปซส่วนกลางต่อไปนี้ อาร์กิวเมนต์ส่วนใหญ่เป็นฟังก์ชันที่ช่วยให้คุณระบุขั้นตอนสําคัญในการเตรียมและแสดงโฆษณาได้ เช่น

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

ฟังก์ชันเหล่านี้ใช้เพื่อวางและกําหนดค่าโฆษณาในเกม อาร์กิวเมนต์ที่แสดงด้านบนเป็นอาร์กิวเมนต์เดียวที่ถูกต้องซึ่งส่งผ่านไปยังฟังก์ชันเหล่านี้ได้ โฆษณาประเภทต่างๆ ต้องใช้ชุดย่อยของอาร์กิวเมนต์เหล่านี้ตามรายละเอียดด้านล่าง

adBreak() เป็นฟังก์ชันหลักสําหรับการวางโฆษณาภายในเกม โดยจะกําหนดตําแหน่งโฆษณา แล้วใช้ออบเจ็กต์ที่เรียกว่าการกําหนดค่าตําแหน่งโฆษณาซึ่งระบุทุกอย่างที่จําเป็นต่อการแสดงโฆษณา

ฟังก์ชัน adBreak() กําหนดตําแหน่งที่โฆษณาจะแสดงได้ การแสดงโฆษณาจริงหรือไม่ขึ้นอยู่กับปัจจัยต่างๆ ต่อไปนี้

  • ประเภทของตําแหน่งโฆษณาที่คุณประกาศ
    • โฆษณานี้เป็นจุดเริ่มต้นของเกมใช่ไหม ระหว่างระดับใช่ไหม ในช่วงเวลาที่ผู้เล่นหยุดเกมไว้ชั่วคราวใช่ไหม
  • มีโฆษณาที่เหมาะสมสําหรับโปรแกรมเล่นปัจจุบันหรือไม่
    • โฆษณานี้เกี่ยวข้องกับพวกเขาหรือไม่
    • การแจ้งเตือนนี้สอดคล้องกับการตั้งค่าความเป็นส่วนตัวของข้อมูลและการขอความยินยอมหรือไม่
  • จํานวนโฆษณาที่ผู้เล่นเห็นเมื่อเร็วๆ นี้
  • การตั้งค่าการควบคุม เช่น ความถี่ของโฆษณาที่คุณกําหนดค่าสําหรับเกมนี้
    • ในรูปแบบคําแนะนําในแท็ก หรือ
    • ภายใน AdSense โปรดทราบว่าการควบคุมที่มีอยู่ใน AdSense จะพัฒนาขึ้นเมื่อเวลาผ่านไป

ประเภทโฆษณาที่แสดงก็ขึ้นอยู่กับปัจจัยที่คล้ายคลึงกันด้วย

โปรดทราบว่าการโทรหา adBreak() อาจไม่แสดงโฆษณาเลย เป็นการประกาศตําแหน่งที่แสดงโฆษณาได้

วิธีนี้ต่างจาก API แบบดั้งเดิมที่โค้ดจะรู้ว่าโฆษณาพร้อมใช้งานหรือไม่ คุณเป็นผู้ตัดสินใจว่าจะแสดงในเกมหรือไม่ วิธีนี้ทําให้ Ad Placement API ตัดสินว่าโฆษณาจะได้แสดงในตําแหน่งใดตําแหน่งหนึ่งหรือไม่ ซึ่งบางครั้งเรียกว่า "การกลับการควบคุม"

เหตุผลที่เราเปลี่ยน API เกมของเราเป็นรูปแบบนี้เป็นอันดับแรก เพราะจะทําให้โค้ดที่คุณเขียนภายในเกมของคุณสั้นลง ประการที่ 2 เครื่องมือนี้ช่วยให้การแสดงตําแหน่งโฆษณาที่เป็นไปตามนโยบายได้รับประสบการณ์ของผู้ใช้ที่ยอดเยี่ยม ซึ่งช่วยให้เรามอบรูปแบบที่มีประสิทธิภาพสูงสุดบางส่วนให้แก่ผู้เผยแพร่เกมได้ สุดท้ายนี้ จะแยกขั้นตอนการวางโฆษณาในเกมออกจากการตัดสินใจเกี่ยวกับการสร้างรายได้และประเภทโฆษณาที่จะแสดงได้อย่างชัดเจน

เราต้องการให้คุณเปลี่ยนการตั้งค่าการสร้างรายได้และควบคุมประสบการณ์ของผู้ใช้ได้โดยไม่ต้องแก้ไขและเผยแพร่เกมเวอร์ชันใหม่ ในช่วงแรกด้วยการระบุคําแนะนําในแท็ก แต่ในการเปิดตัวครั้งต่อไป เราจะสามารถให้การควบคุมในฟรอนท์เอนด์ของ AdSense และ AdMob ได้โดยตรง

โฆษณาคั่นระหว่างหน้า

โฆษณาคั่นระหว่างหน้าเป็นโฆษณาแบบเต็มหน้าจอที่แสดงในช่วงเวลาต่างๆ ภายในเกมได้ เช่น เมื่อผู้เล่นเริ่มเล่นเกมหรือหลังจากที่ผู้เล่นจบด่าน รูปแบบนี้จะหยุดเกมชั่วคราว ครอบคลุมทั้งเอกสาร และผู้เล่นสามารถเลือกที่จะคลิกโฆษณา (ซึ่งในกรณีนี้โฆษณาจะปรากฏในแท็บอื่นของเบราว์เซอร์) หรือปิด ซึ่งช่วยให้ดําเนินการต่อเกมได้

หากต้องการวางโฆษณาคั่นระหว่างหน้า ให้ป้อนข้อมูลในช่องต่อไปนี้ภายในการกําหนดค่าตําแหน่งโฆษณา

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 และเราขอแนะนําให้ตั้งชื่อตําแหน่งเสมอ โค้ดเรียกกลับอื่นๆ เป็นตัวเลือกที่ไม่บังคับ

ลําดับการโทร

ดูลําดับการโทรของโฆษณาคั่นระหว่างหน้า

แผนภาพลําดับการเรียกโฆษณาคั่นระหว่างหน้า

คำอธิบาย

โฆษณาคั่นระหว่างหน้า – ลําดับการโทรโดยละเอียด
เกม H5 ของคุณ API ตําแหน่งโฆษณา
  การเริ่มต้นและการโหลดโฆษณาล่วงหน้า
เปิดเกม  

โอกาสที่ดีในการแสดงโฆษณา...

adBreak() →

 
 

มีโฆษณาที่ใช้ได้และตอนนี้ก็เป็นช่วงเวลาที่ดีในการแสดง...

← beforeAd()
เกมจะหยุดชั่วคราว ปิดเสียง และเตรียมแสดงโฆษณา

return ไปยัง API →

 
  Ad Placement API แสดงผลโฆษณาคั่นระหว่างหน้า โปรแกรมเล่นสามารถคลิกโฆษณา (ซึ่งแสดงในแท็บใหม่) ผู้ใช้ต้องปิดโฆษณาเพื่อเล่นเกมต่อ
  ← afterAd() จะถูกเรียกหากมีการแสดงโฆษณา
เกมจะยกเลิกการหยุดชั่วคราวและเปิดเสียง  
  ← adBreakDone()adBreakDone() เรียกตัวเองเสมอ (แม้ว่าจะไม่แสดงโฆษณา)
เกมบันทึกการวิเคราะห์เกี่ยวกับตําแหน่งโฆษณานี้  

หมายเหตุ

  • adBreak() เป็นฟังก์ชันแบบไม่พร้อมกันซึ่งจะแสดงผลทันที
  • หากไม่มีตําแหน่งโฆษณาที่จะแสดงในตําแหน่งใด จะไม่มีการเรียกโค้ดเรียกกลับ กล่าวคือจะไม่มีการเรียกใช้ beforeAd(),afterAd()
  • เพื่อให้แน่ใจว่าเกมจะไม่ทํางานต่อไปในขณะที่โฆษณาแสดงอยู่ ให้ใช้การเรียกกลับ beforeAd() เพื่อปิดเสียงและหยุดเกมชั่วคราว
  • beforeAd() เป็นแบบไม่พร้อมกัน Ad Placement API จะไม่แสดงโฆษณาจนกว่าจะแสดงผล
  • รีสตาร์ทเกมและเปิดเสียงเมื่อได้รับสาย afterAd()
  • หากระบุ ระบบจะเรียกใช้ adBreakDone() เสมอแม้ว่าโฆษณาจะไม่แสดงในตําแหน่งนี้
  • การเรียก adBreak() ขณะที่แสดงโฆษณาอื่นล้มเหลว และระบบจะแสดงคําเตือนในคอนโซล JavaScript

โฆษณาตอนต้น

โฆษณาตอนต้นคือโฆษณาคั่นระหว่างหน้าที่แสดงก่อนที่เกมจะโหลด UI สิ่งแรกที่ผู้เล่นเห็นเมื่อมาที่เกมของคุณ เนื่องจากโฆษณาตอนต้นเกิดขึ้นเร็วมากในการโหลดหน้าเว็บ และเกมของคุณจึงไม่แสดง การโทรทั่วไปเพื่อปิดเสียงและปิดเสียงเกมชั่วคราวจึงไม่จําเป็น แต่ให้ใช้โค้ดเรียกกลับ adBreakDone() เพื่อเรียงลําดับจุดเริ่มต้นของเกมด้วยโฆษณา ซึ่งก็คือการแสดงผล UI และเริ่มเล่นเสียง มีเพียงทริกเกอร์เดียวเท่านั้นที่จะทริกเกอร์การโหลดหน้าเว็บแต่ละครั้งได้

ลําดับการโทร

การเรียกใช้โฆษณาตอนต้นจะเกิดขึ้นในช่วงต้นของการโหลดหน้าเว็บ เนื่องจากเกมของคุณไม่ได้แสดง UI ในจุดนี้ จึงไม่ควรเรียกการเรียก beforeAd() และ afterAd() ให้ใช้โค้ดเรียกกลับ adBreakDone() เพื่อเริ่มเกมแทนหลังจากตําแหน่งโฆษณา เนื่องจากรับประกันว่าจะมีการเรียกการโทรนี้แม้ว่าจะไม่มีโฆษณาก็ตาม

แผนภาพลําดับการเรียกโฆษณาล่วงหน้า

การเรียกใช้โค้ดต่อไปนี้ในช่วงต้นของตรรกะเกมจะวางโฆษณาโฆษณาตอนต้น คุณไม่ควรแสดง UI ก่อนเรียกใช้โค้ดนี้

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})
โฆษณาตอนต้น - ลําดับการโทรโดยละเอียด
เกม H5 ของคุณ API ตําแหน่งโฆษณา
  เริ่มต้น API และเริ่มต้นแคชโฆษณา
กําลังทํางานแต่ยังไม่ได้เริ่มต้นและยังไม่ได้แสดง UI  

adBreak(type:'preroll',…) →

 
 

Ad Placement API เริ่มต้นการโหลดและโหลดโฆษณาให้เสร็จสิ้น หากมีโฆษณา แสดงอยู่ เครื่องเล่นสามารถคลิกโฆษณา (ซึ่งแสดงในแท็บใหม่) ต้องปิดเพื่อให้เกมเริ่มเล่น

 

← adBreakDone() จะถูกเรียกเสมอ (แม้ว่าจะไม่มีโฆษณาก็ตาม)

UI ของเกมจะถูกแสดงผลบนหน้าจอ และตอนนี้ผู้เล่นสามารถโต้ตอบกับ UI ได้ เกมสามารถใช้ออบเจ็กต์ placementInfo ที่ส่งไปยัง adBreakDone() ได้ตามต้องการ (เช่น เพื่อบันทึกข้อมูลวิเคราะห์เพิ่มเติม)

  

หมายเหตุ

  • โฆษณาตอนต้นจะพยายามโหลดโฆษณาล่วงหน้าเสมอ
    • ไม่จําเป็นต้องโทร adConfig(preloadAds: ‘on') โดยใช้โฆษณาตอนต้น
  • โฆษณาตอนต้นแสดงหรือไม่แสดงโฆษณาก็ได้
  • ไม่ควรส่ง beforeAd() และ afterAd() ไปยังโฆษณาตอนต้น
    • เนื่องจากโฆษณาตอนต้นเริ่มเล่นก่อนเกม คุณจึงไม่จําเป็นต้องหยุดชั่วคราวหรือปิดเสียงเกม
    • หากคุณส่ง beforeAd() หรือ afterAd() พร้อมโฆษณาตอนต้น การโทรจะไม่สําเร็จ และข้อผิดพลาดจะได้รับการบันทึกไว้ในคอนโซล JavaScript
  • โฆษณาตอนต้นจะรอให้ Ad Placement API เริ่มต้นและโหลดโฆษณาล่วงหน้าโดยอัตโนมัติ
    • แต่จะมีระยะหมดเวลา (2 วินาที) ที่ป้องกันไม่ให้มีการโทรล่าช้าได้ไม่รู้จบ วิธีนี้ช่วยให้มั่นใจว่าจะมีการเรียก adBreakDone() ตามแฟชั่นและเริ่มเกมทันที
    • ระบบจะเรียกใช้ adBreakDone() เสมอแม้ว่าจะไม่มีโฆษณาก็ตาม
  • เราขอแนะนําให้คุณใช้โฆษณาตอนต้นเพื่อวางโฆษณาก่อนที่เกมจะเริ่มต้นขึ้น
    • หรืออาจใช้การเรียก onReady() กลับไปยัง adConfig() เป็นกลไกในการเรียงลําดับตรรกะของเกมด้วยการเริ่มต้น API และการโหลดโฆษณาล่วงหน้า

โฆษณาที่มีการให้รางวัล

โฆษณาที่มีการให้รางวัลให้คุณตอบแทนผู้เล่นด้วยไอเทมที่ซื้อในแอปหากเลือกที่จะดูโฆษณา ขณะที่โฆษณาคั่นระหว่างหน้ามีการเลือกไม่ใช้ โปรแกรมเล่นจะแสดงโฆษณาขึ้นและเลือกที่จะปิดได้ โฆษณาที่มีการให้รางวัลเป็นแบบเลือกรับ ผู้เล่นเลือกได้ว่าจะดูโฆษณาหรือไม่และรับรางวัลเมื่อใด

ผู้เล่นต้องดูโฆษณาเป็นระยะเวลาขั้นต่ํา (ซึ่งอาจแตกต่างกันไปตามครีเอทีฟโฆษณาที่แสดงอยู่) ซึ่งต่างจากโฆษณาคั่นระหว่างหน้าที่โปรแกรมเล่นปิดโฆษณาได้ทุกเมื่อเพื่อรับรางวัล

เนื่องจากโฆษณาที่มีการให้รางวัลเป็นส่วนที่ไม่บังคับสําหรับผู้เล่น จึงต้องผสานรวมเข้ากับโฟลว์เกมของคุณในระดับที่ลึกขึ้น คุณต้องระบุฟังก์ชันสําหรับแสดงรางวัลภายในเกม และจัดสรรรางวัลให้กับผู้เล่นหากผู้ชมดูโฆษณา

รางวัลต้องไม่มีมูลค่านอกแอป แอปต้องไม่มี (หรือแลกเปลี่ยนกับ) มูลค่าทางการเงิน และต้องไม่ขายหรือแลกเปลี่ยนเป็นสินค้าและบริการได้ และคุณไม่ควรส่งเสริมให้ผู้เล่นคลิกโฆษณา โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับนโยบายฉบับร่างของโฆษณาคั่นระหว่างหน้าและโฆษณาที่มีการให้รางวัล

เนื่องจากรางวัลเป็นส่วนที่ไม่บังคับสําหรับผู้เล่น คุณจึงเพิ่มรางวัลลงในเกมที่เหมาะสมและใช้นอกเหนือจากโฆษณาคั่นระหว่างหน้าได้ โฆษณา Display ในตําแหน่งเหล่านี้คือโอกาสในการแสดงโฆษณาที่มีการให้รางวัล เช่นเดียวกับโฆษณาคั่นระหว่างหน้า Ad Placement API จะเรียกโค้ดของคุณก็ต่อเมื่อมีการแสดงโฆษณาที่มีการให้รางวัลจริงๆ เมื่อถึงจุดหนึ่งๆ ในเกมเท่านั้น

เป้าหมายอีกครั้งคือเพื่อให้คุณผสานรวมเกมกับ Ad Placement API ได้เพียงครั้งเดียว จากนั้นเมื่อเวลาผ่านไปโดยใช้การควบคุมในแท็กหรือใน AdSense คุณจะสามารถเปลี่ยนการผสมผสานโฆษณาต่างๆ ที่เปิดใช้งานอย่างถูกต้อง โดยไม่ต้องเขียนโค้ดใหม่และเผยแพร่เกมอีกครั้ง

ประเภทของตําแหน่งโฆษณาที่มีการให้รางวัลจะเป็น 'reward' เสมอ และใช้ช่องทั้งหมดในการกําหนดค่าตําแหน่งโฆษณาได้

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

ฟังก์ชันใหม่ที่สําคัญคือ beforeReward() ซึ่งเป็นทริกเกอร์ที่ส่งสัญญาณว่าคุณควรแสดงข้อความแจ้งของรางวัล และจะมีการเรียก adViewed() เมื่อผู้เล่นดูโฆษณาสําเร็จเพื่อให้คุณจัดสรรรางวัลได้

คุณสามารถกําหนดตําแหน่งโฆษณาที่มีการให้รางวัลได้ดังนี้

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

โฆษณาที่มีการให้รางวัลเริ่มต้นด้วยข้อความแจ้งในเกมเพื่อเสนอรางวัลให้ผู้เล่นหากได้ดูโฆษณา

ตัวอย่างข้อความแจ้งโฆษณา: ดูวิดีโอเพื่อรับชีวิตเพิ่ม

ลําดับการโทรสําหรับโฆษณาที่มีการให้รางวัล

แผนภาพลําดับการโทรที่มีการให้รางวัล

คำอธิบาย

โฆษณาที่มีการให้รางวัล - ลําดับการโทรโดยละเอียด
เกม H5 ของคุณ API ตําแหน่งโฆษณา
  การเริ่มต้นและการแคชโฆษณาล่วงหน้า
เปิดเกม  

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

 
 

มีโฆษณาที่ใช้ได้ ดังนั้นให้เริ่มตําแหน่งโฆษณาที่มีการให้รางวัล beforeReward() จะถูกโทรพร้อมกันทันทีหลังจากที่โทรหา adBreak()

← beforeReward(showAdFn)

เกมแสดงข้อความแจ้งรางวัล เพื่อเปิดโอกาสให้ผู้เล่นได้รางวัลจากการดูโฆษณา คุณรับรางวัลมากกว่า 1 ประเภทได้ (เช่น ชีวิตใหม่หรือเหรียญทอง)

ผู้เล่นสามารถคลิกข้อความแจ้งรางวัล ปิด หรือเพียงแค่ไม่สนใจข้อความแจ้งนั้นได้

หากเพื่อนคลิกข้อความแจ้ง เกมก็จะจัดเก็บประเภทของรางวัลที่ขอและโทรหา showAdFn()...

ไม่เช่นนั้นระบบจะปิดหรือละเว้นข้อความแจ้งของรางวัลจนกว่าคุณจะเรียกใช้ adBreak() อีกครั้ง โดยใช้ประเภทตําแหน่งรางวัลที่ Ad Placement API จะรีเซ็ตและล้างสถานะออกจากการเรียกนี้ หากแอปเรียก showAdFn จากช่วงพักโฆษณาก่อนหน้า จะไม่มีผลใดๆ

  

showAdFn() →

 
  ← beforeAd()

เกมหยุดชั่วคราว ปิดเสียง และเตรียมแสดงโฆษณา

return ไปยัง API →

 
  API จะแสดงโฆษณา โดยมีปุ่มปิดและนับถอยหลังเวลาที่เหลือในโฆษณา
หากโปรแกรมเล่นปิดโฆษณา...
  ← adDismissed()
ผู้เล่นปิดโฆษณาและเกมจะไม่ออกรางวัล  
หรือให้ผู้เล่นดูโฆษณาจนจบ...
  ← adViewed()
ผู้เล่นดูโฆษณาจนจบและเกมต้องได้รับรางวัล (โดยปกติจะเป็นการตั้งค่าสถานะเกมซึ่งจะไปรับเมื่อเกมรีสตาร์ทที่มีการเรียกไปยัง afterAd() ด้านล่าง)  
หลังจากที่ผู้ใช้ดูหรือปิดโฆษณาแล้ว
  ← afterAd() จะถูกเรียกหากมีการแสดงโฆษณา
เกมจะยกเลิกการหยุดชั่วคราวและเปิดเสียง  
  ← adBreakDone()adBreakDone() เรียกตัวเองเสมอ (แม้ว่าจะไม่แสดงโฆษณา)
เกมบันทึกการวิเคราะห์เกี่ยวกับตําแหน่งโฆษณานี้  

หมายเหตุ

  • adBreak() เป็นฟังก์ชันแบบไม่พร้อมกันซึ่งจะแสดงผลทันที
  • หากไม่มีตําแหน่งโฆษณาที่จะแสดงสําหรับตําแหน่งใด จะไม่มีการเรียกโค้ดเรียกกลับ กล่าวคือจะไม่มีการเรียกใช้ beforeAd() และ beforeReward()
  • เพื่อให้แน่ใจว่าเกมจะไม่ทํางานต่อไปในขณะที่โฆษณาแสดงอยู่ ให้ใช้การเรียกกลับ beforeAd() เพื่อปิดเสียงและหยุดเกมชั่วคราว
  • beforeAd() เป็นแบบไม่พร้อมกัน Ad Placement API จะไม่แสดงโฆษณาจนกว่าจะแสดงผล
  • รีสตาร์ทเกมและเปิดเสียงเมื่อได้รับสาย afterAd()
  • หากระบุ ระบบจะเรียกใช้ adBreakDone() เสมอแม้ว่าโฆษณาจะไม่แสดงในตําแหน่งนี้
  • การเรียก adBreak() ขณะที่แสดงโฆษณาอื่นล้มเหลว และระบบจะแสดงคําเตือนในคอนโซล JavaScript