adBreak()

ลายเซ็นของฟังก์ชัน:

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 re-enable 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
);

พารามิเตอร์ adBreak()

ชื่อ ประเภท คำอธิบาย
ประเภทตําแหน่งทั้งหมด
type สตริง

ประเภทของตําแหน่ง ค่า:

  • 'preroll' ก่อนที่เกมจะโหลด (ก่อนแสดงผล UI)
  • 'start' ก่อนที่เกมเพลย์จะเริ่ม (หลังจากแสดงผล UI)
  • 'pause' ผู้เล่นหยุดเกมชั่วคราว
  • ผู้เล่น 'next' คนเพื่อไปที่ระดับถัดไป
  • 'browse' ผู้เล่นสํารวจตัวเลือกนอกเกม
  • 'reward' โฆษณาที่มีการให้รางวัล
name สตริง (ไม่บังคับ) ชื่อตําแหน่งโฆษณานี้ภายในเกม ตัวระบุนี้เป็นตัวระบุภายในและจะไม่แสดงให้ผู้เล่นเห็น ในรุ่นถัดไป ตัวระบุนี้อาจใช้เพื่อเปิดใช้ฟีเจอร์การรายงานและการเพิ่มประสิทธิภาพเพิ่มเติม

เราขอแนะนําให้คุณตั้งชื่อทุกตําแหน่ง
beforeAd ฟังก์ชัน (ไม่บังคับ) โทรก่อนที่โฆษณาจะแสดง เกมควรหยุดชั่วคราวและปิดเสียง โดยจะต้องดําเนินการเหล่านี้พร้อมกัน โฆษณาจะแสดงทันทีหลังจากที่โค้ดเรียกกลับนี้เสร็จสิ้น
afterAd ฟังก์ชัน (ไม่บังคับ) โทรหลังจากที่โฆษณาจบแล้ว (ด้วยเหตุผลใดก็ได้) สําหรับโฆษณาที่มีการให้รางวัล จะเรียกว่าหลัง adDismissed หรือ adViewed ทั้งนี้ขึ้นอยู่กับการทํางานของผู้เล่น ควรใช้ฟังก์ชันนี้เพื่อให้เกมเล่นต่อได้ เช่น ใช้ในการเปิดเสียงและเริ่มระดับถัดไป
adBreakDone ฟังก์ชัน (ไม่บังคับ) เป็นขั้นตอนสุดท้ายใน adBreak() เสมอ แม้ว่าจะไม่มีการแสดงโฆษณา ฟังก์ชันจะใช้เป็นอาร์กิวเมนต์ออบเจ็กต์ placementInfo ที่กําหนดไว้ดังนี้ 
{
    breakType: '<type>',
    breakName: '<name>',
    breakFormat: 'interstitial|reward',
    breakStatus:  'error|noAdPreloaded|...|viewed',
}
ดูคําอธิบายโดยละเอียดของออบเจ็กต์ข้อมูลตําแหน่งได้ที่ adBreakDone และ placementInfo()
ตําแหน่งที่มีการให้รางวัลเท่านั้น...
beforeReward ฟังก์ชัน เรียกใช้หากมีโฆษณาที่มีการให้รางวัล ฟังก์ชันควรใช้อาร์กิวเมนต์เดียว showAdFn() ซึ่งต้องเรียกเพื่อแสดงโฆษณาที่มีการให้รางวัล
adDismissed ฟังก์ชัน เรียกว่าโฆษณาที่มีการให้รางวัลเท่านั้นเมื่อโปรแกรมเล่นปิดโฆษณา ซึ่งจะเรียกก็ต่อเมื่อโปรแกรมเล่นปิดโฆษณาก่อนที่โฆษณาจะจบเท่านั้น ในกรณีนี้ คุณไม่ควรได้รับรางวัล
adViewed ฟังก์ชัน เรียกใช้เฉพาะสําหรับโฆษณาที่มีการให้รางวัลเมื่อผู้เล่นเล่นจบโฆษณาและควรได้รับรางวัล

adBreakDone() and placementInfo

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

ฟังก์ชัน adBreakDone() จะใช้เป็นอาร์กิวเมนต์ออบเจ็กต์ placementInfo ที่กําหนดไว้ดังนี้

{
  breakType: '<type>',
  breakName: '<name>',
  breakFormat: 'interstitial|reward',
  breakStatus: 'notReady|timeout|error|noAdPreloaded|frequencyCapped|ignored|other|dismissed|viewed',
}

เมื่อช่องภายในออบเจ็กต์นี้มีความหมายต่อไปนี้

  • breakType คืออาร์กิวเมนต์ประเภทที่ส่งไปยัง adBreak()
  • breakName คืออาร์กิวเมนต์ชื่อที่ส่งไปยัง adBreak()
  • breakStatus คือสถานะของตําแหน่งนี้และอาจเป็นค่าใดค่าหนึ่งต่อไปนี้
breakStatus เหตุผล
'notReady' Ad Placement API ไม่ได้เริ่มต้น
'timeout' ตําแหน่งโฆษณาหมดเวลาเนื่องจาก Ad Placement API ใช้เวลาตอบกลับนานเกินไป
'invalid' ตําแหน่งไม่ถูกต้องและถูกละเว้น เช่น ควรมีตําแหน่งโฆษณาตอนต้นเพียง 1 ตําแหน่งต่อการโหลดหน้าเว็บ โฆษณาตอนต้นจึงล้มเหลวตามลําดับ
'error' เกิดข้อผิดพลาด JavaScript ในการเรียกกลับ
'noAdPreloaded' ยังไม่มีการโหลดโฆษณาล่วงหน้า ตําแหน่งนี้จึงถูกข้าม
'frequencyCapped' โฆษณาไม่แสดงเนื่องจากมีการใช้ความถี่สูงสุดกับตําแหน่งโฆษณานี้
'ignored' ผู้ใช้ไม่ได้คลิกข้อความแจ้งรางวัลก่อนที่จะไปถึงตําแหน่งถัดไป กล่าวคือระบบไม่ได้เรียก showAdFn() ก่อน adBreak() ครั้งต่อไป
'other' โฆษณาไม่แสดงเนื่องจากเหตุผลอื่น (เช่น ระบบยังดึงข้อมูลโฆษณาอยู่หรือได้ทําการแคชโฆษณาก่อนหน้านี้ เนื่องจากมีการปรับขนาด/หมุนหน้าจอ)
'dismissed' ผู้ใช้ปิดโฆษณาที่มีการให้รางวัลก่อนที่จะดูจนจบ
'viewed' ผู้ใช้ดูโฆษณา

หมายเหตุ: adBreakDone() เป็นการโทรกลับครั้งสุดท้ายที่ adBreak() โทรเสมอ

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