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 string

刊登位置類型。值：

  • 遊戲載入前 (UI 轉譯前) 的 'preroll'
  • 遊戲開始前 (在 UI 轉譯後) 前 'start'
  • 'pause'玩家會暫停遊戲
  • 'next' 名玩家將進入下一級
  • 'browse'玩家會探索遊戲過程以外的選項
  • 'reward' 則獎勵廣告
name string (選用) 這個遊戲中特定廣告刊登位置的名稱。這是內部 ID，不會向玩家顯示。在日後推出的版本中，這個 ID 可能會用來啟用其他報表和最佳化功能。

建議您將所有刊登位置命名。
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' 刊登位置無效且已遭忽略。舉例來說，假設網頁載入時只有一個刊登位置刊登位置，後續的片頭廣告就會失敗，並顯示這個狀態
'error' 回呼中有 JavaScript 錯誤
'noAdPreloaded' 廣告尚未預先載入，因此已略過這個刊登位置
'frequencyCapped' 這個展示頻率上限已套用至這個刊登位置，因此無法顯示
'ignored' 使用者沒有在抵達下一個刊登位置前點擊獎勵提示，也就是在下一個adBreak()之前未呼叫 showAdFn()。
'other' 廣告基於其他原因而無法顯示。(例如：系統仍在擷取廣告，或是因為螢幕已調整/旋轉畫面，導致先前快取的廣告遭到棄置)。
'dismissed' 使用者在觀看獎勵廣告前就關閉了獎勵廣告
'viewed' 使用者觀看了廣告

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

如果您使用 afterAd() 讓遊戲在廣告放送後取消暫停，系統會在遊戲重新啟動後呼叫 adBreakDone()。雖然記錄分析可能也許有所幫助，但如果您想在遊戲重新啟動前執行其他工作，請將邏輯從afterAd()從 adBreakDone() 取消暫停。