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 函数 (可选)无论出于任何原因,都应在广告展示完毕后调用。对于激励广告,此方法会在 adDismissedadViewed 之后调用,具体取决于玩家操作。此函数应该用于恢复游戏流程。例如,用于取消静音并开始下一关。
adBreakDone 函数 (可选)始终作为 adBreak() 中的最后一步调用,即使广告没有展示也是如此。函数将作为 placementInfo 对象定义的参数,如下所示:

{
    breakType: '<type>',
    breakName: '<name>',
    breakFormat: 'interstitial|reward',
    breakStatus:  'error|noAdPreloaded|...|viewed',
}
如需详细了解展示位置信息对象,请参阅 adBreakDoneplacementInfo()
仅限激励广告展示位置…
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()