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'（界面呈现之前）
  • 游戏开始前的 'start'（界面呈现之后）
  • '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' 展示位置无效并已被忽略。例如，每次网页加载时应只有一个前贴片广告展示位置，后续的前贴片广告都无法投放并显示此状态
'error' 回调中存在 JavaScript 错误
'noAdPreloaded' 广告尚未预加载，因此跳过了此展示位置
'frequencyCapped' 由于向此展示位置应用了频次上限，因此广告未能展示
'ignored' 用户在到达下一个展示位置之前没有点击奖励提示，即在下一个 adBreak() 之前没有调用 showAdFn()。
'other' 广告因其他原因未能展示。（例如，系统仍在提取广告，或之前缓存的广告因屏幕大小调整/旋转而被清理。）
'dismissed' 用户在看完激励广告之前将其关闭了
'viewed' 用户观看了广告

注意：adBreakDone() 始终是 adBreak() 调用的最后一个回调。

如果您使用 afterAd() 在广告展示后取消暂停游戏，系统会在游戏重新开始后调用 adBreakDone()。可能适用于记录分析数据等操作，但如果您想在游戏重新开始之前执行其他操作，请将取消暂停游戏的逻辑从 afterAd() 改为 adBreakDone()。