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 字串 (選用)：遊戲中這個特定廣告刊登位置的名稱。這是內部 ID，不會向玩家顯示。日後發布的版本可能會使用這個 ID，啟用其他報表和最佳化功能。

建議您為所有刊登位置命名。
beforeAd 函式 (選用) 廣告顯示前呼叫。遊戲應會暫停並靜音。這些動作必須同步完成。這個回呼完成後，系統會立即顯示廣告。
afterAd 函式 (選用)：廣告結束後 (不論是基於任何原因) 呼叫。如果是獎勵廣告，則會根據玩家的動作，在 adDismissed 或 adViewed「之後」呼叫。這個函式應可繼續遊戲流程。例如，用來取消靜音並開始下一個關卡。
adBreakDone 函式 (OPTIONAL) Always called as the last step in an adBreak(), even if there was no ad shown. 函式會將 placementInfo 物件做為引數，定義如下：
{
    breakType: '<type>',
    breakName: '<name>',
    breakFormat: 'interstitial|reward',
    breakStatus:  'error|noAdPreloaded|...|viewed',
}
 如要詳細瞭解刊登位置資訊物件，請參閱 adBreakDone 和 placementInfo()。
僅限獎勵刊登位置...
beforeReward 函式 如果可放送獎勵廣告，系統就會呼叫這個方法。這個函式應採用單一引數 showAdFn()，且必須呼叫該引數才能顯示獎勵廣告。
adDismissed 函式 只有在玩家關閉獎勵廣告時，才會針對獎勵廣告呼叫這個方法。只有在播放器在廣告播完前關閉廣告時，才會呼叫這個函式。在這種情況下，不應授予獎勵。
adViewed 函式 只有在播放器播放完獎勵廣告，且應授予獎勵時，才會呼叫這個函式。

adBreakDone() and placementInfo

如果廣告刊登位置 API 沒有可顯示的廣告，就不會呼叫您傳遞的各種 before/after 回呼。不過，如果您提供 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' 刊登位置無效，因此遭到忽略。舉例來說，每個網頁載入作業只能有一個前置廣告刊登位置，後續前置廣告會因這個狀態而失敗
'error' 回呼中發生 JavaScript 錯誤
'noAdPreloaded' 廣告尚未預先載入，因此系統略過這個刊登位置
'frequencyCapped' 由於這個刊登位置套用了展示頻率上限，因此廣告未顯示
'ignored' 使用者在到達下一個刊登位置前，未點選獎勵提示，也就是說，下一個 adBreak() 之前未呼叫 showAdFn()。
'other' 廣告未顯示的原因是其他因素。(例如：系統仍在擷取廣告，或先前快取的廣告已遭捨棄，因為螢幕大小已調整/旋轉)。
'dismissed' 使用者在獎勵廣告播放完畢前關閉廣告
'viewed' 使用者觀看廣告

注意：adBreakDone() 一律是 adBreak() 呼叫的最後一個回呼。

如果廣告顯示後，您使用 afterAd() 取消暫停遊戲，遊戲重新啟動後就會呼叫 adBreakDone()。如果是記錄 Analytics 等工作，這或許很合適，但如果想在遊戲重新啟動前執行其他工作，請將遊戲取消暫停的邏輯從 afterAd() 移至 adBreakDone()。