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 ของเกมไปใช้โมเดลนี้คือประการแรก โมเดลนี้จะ ลดความยาวของโค้ดที่คุณต้องเขียนภายในเกม ประการที่สอง การดำเนินการนี้ช่วยให้เรา ส่งมอบตําแหน่งที่สอดคล้องกับนโยบายพร้อมประสบการณ์การใช้งานที่ยอดเยี่ยม ซึ่งช่วยให้เราสามารถส่งมอบรูปแบบที่มีประสิทธิภาพสูงสุด ให้กับผู้เผยแพร่เกม สุดท้ายนี้ การแยกกระบวนการแสดงโฆษณาในเกมออกจากตัวเลือกการสร้างรายได้เกี่ยวกับประเภทและจำนวนโฆษณาที่จะแสดงจะทำให้กระบวนการต่างๆ ชัดเจนยิ่งขึ้น
เราต้องการให้คุณเปลี่ยนการตั้งค่าการสร้างรายได้และควบคุมประสบการณ์ของผู้ใช้ได้โดยไม่ต้องแก้ไขและเผยแพร่เกมเวอร์ชันใหม่ โดยเริ่มจากการระบุคำแนะนำในแท็ก แต่ในรุ่นต่อๆ ไป เราจะสามารถให้การควบคุมได้โดยตรงในส่วนหน้าของ AdSense และ AdMob
โฆษณาคั่นระหว่างหน้า
โฆษณาคั่นระหว่างหน้าเป็นโฆษณาแบบเต็มหน้าจอที่แสดงได้ในเวลาต่างๆ ภายในเกม เช่น เมื่อผู้เล่นเริ่มเกม หรือหลังจากผู้เล่นเล่นจบด่าน โดยจะหยุดเกมชั่วคราว ครอบคลุมทั้งเอกสาร และ ผู้เล่นสามารถเลือกคลิกโฆษณา (ในกรณีนี้โฆษณาจะแสดงในแท็บอื่น ของเบราว์เซอร์) หรือปิดโฆษณาเพื่อเล่นเกมต่อได้
หากต้องการแสดงโฆษณาคั่นระหว่างหน้า ให้กรอกข้อมูลในช่องต่อไปนี้ภายใน config ของตําแหน่ง
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 ของคุณ | Ad Placement API |
การเริ่มต้นและการโหลดโฆษณาล่วงหน้า | |
การเล่นเกม | |
โอกาสที่ดีในการแสดงโฆษณา...
|
|
มีโฆษณาพร้อมแสดงและตอนนี้เป็นเวลาที่เหมาะสมที่จะแสดงโฆษณา... ← |
|
เกมจะหยุดชั่วคราว ปิดเสียง และเตรียมพร้อมที่จะแสดงโฆษณา
|
|
API ตำแหน่งโฆษณาจะแสดงโฆษณาคั่นระหว่างหน้า ผู้เล่นสามารถคลิกโฆษณา (ซึ่งจะแสดงในแท็บใหม่) ผู้ใช้ต้องปิดโฆษณาเพื่อเล่นเกมต่อ | |
← afterAd() จะเรียกใช้หากมีการแสดงโฆษณา
|
|
เกมจะกลับมาเล่นต่อและเปิดเสียง | |
← adBreakDone() adBreakDone() จะเรียกใช้เสมอ (แม้ว่าจะไม่มีการแสดงโฆษณาก็ตาม) |
|
เกมจะบันทึกข้อมูลวิเคราะห์เกี่ยวกับตําแหน่งนี้ |
หมายเหตุ
adBreak()
เป็นฟังก์ชันแบบอะซิงโครนัสที่แสดงผลทันที- หากไม่มีโฆษณาที่จะแสดงสำหรับตําแหน่งใดก็ตาม ระบบจะไม่เรียกใช้แฮนเดิลการเรียกกลับใดๆ
นั่นคือจะไม่เรียกใช้
beforeAd()
afterAd()
- เพื่อให้แน่ใจว่าเกมจะไม่ทำงานต่อไปขณะที่โฆษณากำลังแสดง ให้ใช้
beforeAd()
การเรียกกลับเพื่อปิดเสียงและหยุดเกมชั่วคราว beforeAd()
เป็นแบบซิงโครนัส Ad Placement API จะไม่แสดงโฆษณาจนกว่าจะมีการส่งคืน- รีสตาร์ทเกมและเปิดเสียงเมื่อได้รับ
afterAd()
สาย - หากระบุไว้ ระบบจะเรียกใช้
adBreakDone()
เสมอ แม้ว่าจะไม่มีการแสดงโฆษณาใน ตําแหน่งนี้ก็ตาม - การเรียกใช้
adBreak()
ขณะที่โฆษณาอื่นแสดงอยู่จะล้มเหลวและคำเตือนจะ แสดงในคอนโซล JavaScript
โฆษณาตอนต้น
โฆษณาตอนต้นคือโฆษณาคั่นระหว่างหน้าที่แสดงก่อนที่เกมจะโหลด UI ซึ่งเป็นสิ่งแรกที่ผู้เล่นเห็นเมื่อไปยังเกมของคุณ เนื่องจากโฆษณาก่อนวิดีโอ
จะแสดงตั้งแต่ช่วงแรกๆ ของการโหลดหน้าเว็บ และเกมยังไม่แสดง
จึงไม่จำเป็นต้องเรียกใช้ฟังก์ชันเพื่อหยุดชั่วคราวและปิดเสียงเกมตามปกติ แต่คุณจะใช้
adBreakDone()
การเรียกกลับเพื่อจัดลำดับการเริ่มต้นเกมพร้อมกับโฆษณา
นั่นคือ แสดงผล UI และเริ่มเล่นเสียง ระบบจะทริกเกอร์โฆษณา Pre-roll ได้เพียงรายการเดียว
สําหรับการโหลดแต่ละหน้า
ลำดับการโทร
ระบบจะเรียกใช้โฆษณาก่อนวิดีโอตั้งแต่เนิ่นๆ เมื่อโหลดหน้าเว็บ เนื่องจากเกมของคุณยังไม่ได้
แสดงผล UI ในตอนนี้ คุณจึงไม่ควรส่งการเรียกกลับ beforeAd()
และ
afterAd()
แต่ให้ใช้การเรียกกลับ adBreakDone()
เพื่อเริ่มเกมหลังจากตำแหน่ง เนื่องจากระบบรับประกันว่าจะเรียกใช้การเรียกกลับนี้แม้ว่าจะไม่มีโฆษณาก็ตาม
การเรียกโค้ดต่อไปนี้ในช่วงต้นของตรรกะเกมจะแสดงโฆษณาก่อนเล่น ไม่ควรแสดงผล UI ก่อนที่จะเรียกใช้โค้ดนี้
// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
type: ‘preroll',
adBreakDone: startGame,
})
โฆษณาก่อนวิดีโอ - ลำดับการเรียกใช้โดยละเอียด | |
---|---|
เกม H5 ของคุณ | Ad Placement API |
การเริ่มต้น API และการแคชโฆษณาล่วงหน้าเริ่มต้นขึ้น | |
กำลังทำงานแต่ยังไม่เริ่มและยังไม่ได้แสดง UI | |
|
|
Ad Placement API จะเริ่มต้นและโหลดโฆษณาเสร็จสมบูรณ์ หากมีโฆษณา ระบบจะแสดงโฆษณานั้น ผู้เล่นสามารถคลิกโฆษณา (ซึ่งจะแสดงในแท็บใหม่) โดยผู้เล่นจะต้องปิดข้อความนี้เพื่อให้เกมเริ่มได้ |
|
← |
|
ระบบจะแสดง UI ของเกมบนหน้าจอและตอนนี้ผู้เล่นสามารถโต้ตอบกับ UI ได้แล้ว เกมสามารถใช้ออบเจ็กต์ |
หมายเหตุ
- โฆษณาตอนต้นจะพยายามโหลดโฆษณาล่วงหน้าเสมอ
- ไม่จำเป็นต้องเรียกใช้
adConfig(preloadAds: ‘on')
กับโฆษณาก่อนวิดีโอ
- ไม่จำเป็นต้องเรียกใช้
- เหมือนกับตําแหน่งโฆษณาอื่นๆ พรีโรลอาจแสดงโฆษณาหรือไม่ก็ได้
- ไม่ควรส่ง
beforeAd()
และafterAd()
ไปยังโฆษณาตอนต้น- เนื่องจากโฆษณาตอนต้นจะแสดงก่อนที่เกมจะเริ่ม จึงไม่จำเป็นต้องหยุดชั่วคราว หรือปิดเสียงเกม
- หากส่ง
beforeAd()
หรือafterAd()
พร้อมกับโฆษณาตอนต้น การเรียกจะ ล้มเหลวและระบบจะบันทึกข้อผิดพลาดลงในคอนโซล JavaScript
- โฆษณาตอนต้นจะรอให้ API ตำแหน่งโฆษณาเริ่มต้นและโหลดโฆษณาล่วงหน้าโดยอัตโนมัติ
- อย่างไรก็ตาม มีการหมดเวลา (2 วินาที) ที่ป้องกันไม่ให้การเรียกใช้ล่าช้า
อย่างไม่มีกำหนด ซึ่งจะช่วยให้เรียกใช้
adBreakDone()
ได้ทันท่วงที และเกมของคุณจะเริ่มทำงาน adBreakDone()
จะได้รับการเรียกใช้เสมอแม้ว่าจะไม่มีโฆษณาก็ตาม
- อย่างไรก็ตาม มีการหมดเวลา (2 วินาที) ที่ป้องกันไม่ให้การเรียกใช้ล่าช้า
อย่างไม่มีกำหนด ซึ่งจะช่วยให้เรียกใช้
- เราขอแนะนำให้คุณใช้โฆษณาก่อนวิดีโอเพื่อลงโฆษณาก่อนที่เกมจะเริ่ม
- หรือคุณจะใช้
onReady()
การเรียกกลับไปยังadConfig()
เป็นกลไกในการจัดลำดับตรรกะของเกมกับการเริ่มต้น API และการโหลดโฆษณาล่วงหน้าก็ได้
- หรือคุณจะใช้
โฆษณาที่มีการให้รางวัล
โฆษณาที่มีการให้รางวัลช่วยให้คุณสามารถให้รางวัลผู้เล่นด้วยไอเทมที่ซื้อในแอปหากผู้เล่นเลือก ดูโฆษณา ในขณะที่โฆษณาคั่นระหว่างหน้าเป็นแบบเลือกไม่ใช้ ผู้เล่นจะเห็นโฆษณา และเลือกปิดโฆษณาได้ โฆษณาที่มีการให้รางวัลเป็นแบบเลือกใช้ ผู้เล่นเลือกได้ว่าจะดูโฆษณาเมื่อใดเพื่อรับรางวัล
ไม่เหมือนกับโฆษณาคั่นหน้าที่ผู้เล่นสามารถปิดโฆษณาได้ทุกเมื่อ แต่หากต้องการรับรางวัล ผู้เล่นต้องดูโฆษณาเป็นระยะเวลาขั้นต่ำ (ซึ่งอาจแตกต่างกันไปขึ้นอยู่กับครีเอทีฟโฆษณาที่แสดง)
เนื่องจากโฆษณาที่มีการให้รางวัลเป็นตัวเลือกสำหรับผู้เล่น จึงต้องมีการผสานรวมที่ลึกซึ้งยิ่งขึ้น ในโฟลว์ของเกม คุณต้องระบุฟังก์ชันเพื่อแสดงข้อความแจ้งเกี่ยวกับรางวัลภายในเกม และจัดสรรรางวัลให้กับผู้เล่นหากผู้เล่นดูโฆษณา
รางวัลต้องไม่มีค่านอกเหนือจากแอปของคุณ ต้องไม่มีมูลค่าทางการเงิน (หรือแลกเปลี่ยนเป็นมูลค่าทางการเงินได้ง่าย) และต้องไม่สามารถนำไปขายหรือแลกเปลี่ยนเป็นสินค้าและบริการได้ และคุณไม่ควรสนับสนุนให้ผู้เล่นคลิกโฆษณา โปรดดูรายละเอียดเพิ่มเติมในนโยบายฉบับร่างสำหรับโฆษณาคั่นระหว่างหน้าและโฆษณาที่มีการให้รางวัล
เนื่องจากรางวัลเป็นสิ่งที่ผู้เล่นจะรับหรือไม่ก็ได้ คุณจึงเพิ่มรางวัลได้ทุกที่ที่ เหมาะสมภายในเกม และใช้รางวัลร่วมกับโฆษณาคั่นกลางได้ ตําแหน่งเหล่านี้เป็นโอกาสในการแสดงโฆษณาที่มีการให้รางวัลเช่นเดียวกับโฆษณาคั่นระหว่างหน้า 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 ของคุณ | Ad Placement API |
การเริ่มต้นและการแคชโฆษณาล่วงหน้า | |
การเล่นเกม | |
|
|
มีโฆษณาพร้อมใช้งานแล้ว ให้เริ่มตําแหน่งโฆษณาที่มีการให้รางวัล ← |
|
เกมแสดงข้อความแจ้งรางวัล ซึ่งจะช่วยให้ผู้เล่นมีโอกาสได้รับรางวัลจากการดูโฆษณา คุณอาจเสนอรางวัลได้มากกว่า 1 ประเภท (เช่น ชีวิตใหม่หรือเหรียญทอง) ผู้เล่นสามารถคลิกข้อความแจ้งรางวัล ปิดข้อความ หรือไม่สนใจข้อความก็ได้ หากผู้ใช้คลิกข้อความแจ้ง เกมจะจัดเก็บประเภทรางวัลที่ผู้ใช้ขอและเรียกใช้ มิเช่นนั้น หากปิดหรือเพิกเฉยต่อข้อความแจ้งให้รับรางวัล จะไม่มีอะไรเกิดขึ้นจนกว่าคุณจะเรียกใช้ |
|
|
|
← beforeAd() |
|
เกมหยุดชั่วคราว ปิดเสียง และเตรียมพร้อมที่จะแสดงโฆษณา
|
|
API จะแสดงโฆษณา โดยจะมีปุ่มปิดและการนับถอยหลังของระยะเวลาที่เหลือในโฆษณา | |
หากเพลเยอร์ปิดโฆษณา... | |
← adDismissed() |
|
ผู้เล่นปิดโฆษณาและเกมไม่ได้ให้รางวัล | |
ELSE ผู้เล่นจะดูโฆษณาจนจบ... | |
← adViewed() |
|
ผู้เล่นดูโฆษณาจนจบและเกมมอบรางวัลให้ (โดยปกติแล้วจะทำได้ด้วยการตั้งค่าสถานะเกมบางอย่างซึ่งจะนำมาใช้เมื่อเกมรีสตาร์ทด้วยการเรียกใช้ afterAd() ด้านล่าง)
|
|
หลังจากดูหรือปิดโฆษณาแล้ว... | |
← afterAd() จะเรียกใช้หากมีการแสดงโฆษณา |
|
เกมจะกลับมาเล่นต่อและเปิดเสียง | |
← adBreakDone() adBreakDone() จะเรียกใช้เสมอ (แม้ว่าจะไม่มีการแสดงโฆษณาก็ตาม) |
|
เกมจะบันทึกข้อมูลวิเคราะห์เกี่ยวกับตําแหน่งนี้ |
หมายเหตุ
adBreak()
เป็นฟังก์ชันแบบอะซิงโครนัสที่แสดงผลทันที- หากไม่มีโฆษณาที่จะแสดงสำหรับตําแหน่งใด ระบบจะไม่เรียกใช้แฮนเดิลการเรียกกลับใดๆ นั่นคือจะไม่เรียกใช้
beforeAd()
,beforeReward()
- เพื่อให้แน่ใจว่าเกมจะไม่ทำงานต่อไปขณะที่โฆษณากำลังแสดง ให้ใช้
beforeAd()
การเรียกกลับเพื่อปิดเสียงและหยุดเกมชั่วคราว beforeAd()
เป็นแบบซิงโครนัส Ad Placement API จะไม่แสดงโฆษณาจนกว่าจะมีการส่งคืน- รีสตาร์ทเกมและเปิดเสียงเมื่อได้รับ
afterAd()
สาย - หากระบุไว้ ระบบจะเรียกใช้
adBreakDone()
เสมอ แม้ว่าจะไม่มีการแสดงโฆษณาใน ตําแหน่งนี้ก็ตาม - การเรียกใช้
adBreak()
ขณะที่โฆษณาอื่นแสดงอยู่จะล้มเหลวและคำเตือนจะ แสดงในคอนโซล JavaScript