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()
。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-07-26。
[null,null,["最后更新时间 (UTC):2025-07-26。"],[[["\u003cp\u003e\u003ccode\u003eadBreak()\u003c/code\u003e is the primary function for displaying ads, accepting parameters to define ad types, timing, and behaviors.\u003c/p\u003e\n"],["\u003cp\u003eIt offers a variety of placement types like 'preroll', 'start', 'pause', 'next', 'browse', and 'reward' to integrate ads seamlessly into the game flow.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can utilize provided callbacks (\u003ccode\u003ebeforeAd\u003c/code\u003e, \u003ccode\u003eafterAd\u003c/code\u003e, \u003ccode\u003eadBreakDone\u003c/code\u003e, etc.) to manage game states (pause/resume, mute/unmute) and reward users upon ad completion.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eadBreakDone()\u003c/code\u003e callback, always invoked, offers valuable insights into ad delivery outcomes through the \u003ccode\u003eplacementInfo\u003c/code\u003e object, which includes details like \u003ccode\u003ebreakStatus\u003c/code\u003e (e.g., 'viewed', 'dismissed', 'error').\u003c/p\u003e\n"],["\u003cp\u003eFor rewarded ads, the \u003ccode\u003ebeforeReward\u003c/code\u003e callback empowers developers to prompt users with a reward offer, triggering the ad display only upon user acceptance using the provided \u003ccode\u003eshowAdFn()\u003c/code\u003e.\u003c/p\u003e\n"]]],["The `adBreak()` function manages ad placements within a game. Key actions include defining the ad `type` and optional `name`, and providing functions for `beforeAd` (pause/mute game), `afterAd` (resume game), and `beforeReward` (show reward prompt). `adDismissed` and `adViewed` are for rewarded ads. `adBreakDone` is always executed, providing `placementInfo` (type, name, format, status), indicating if an ad was shown and its outcome. Statuses include `viewed`, `dismissed`, `error`, and `noAdPreloaded`.\n"],null,["# adBreak()\n\nFunction signature: \n\n adBreak(\n type: '\u003ctype\u003e', // The type of this placement\n name: '\u003cname\u003e', // A descriptive name for this placement\n beforeAd: () =\u003e {}, // Prepare for the ad. Mute and pause the game flow\n afterAd: () =\u003e {}, // Resume the game and re-enable sound\n beforeReward: (showAdFn) =\u003e {}, // Show reward prompt (call showAdFn() if clicked)\n adDismissed: () =\u003e {}, // Player dismissed the ad before completion\n adViewed: () =\u003e {}, // Ad was viewed and closed\n adBreakDone: (placementInfo) =\u003e {}, // Always called (if provided) even if an ad didn't show\n );\n\nadBreak() parameters\n--------------------\n\n| Name | Type | Description |\n|----------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| All placement types |||\n| `type` | string | The type of the placement. Values: - `'preroll'` before the game loads (before UI has rendered) - `'start'` before the gameplay starts (after UI has rendered) - `'pause'` the player pauses the game - `'next'` player navigates to the next level - `'browse'` the player explores options outside of the gameplay - `'reward'` a rewarded ad |\n| `name` | string | **(OPTIONAL)** a name for this particular ad placement within your game. It is an internal identifier, and is not shown to the player. In future releases this identifier may be used to enable additional reporting and optimization features. We recommend you name all of your placements. |\n| `beforeAd` | function | **(OPTIONAL)** Called before the ad is displayed. The game should pause and mute the sound. These actions must be done synchronously. The ad will be displayed immediately after this callback finishes. |\n| `afterAd` | function | **(OPTIONAL)** Called after the ad is finished (for any reason). For rewarded ads, it is called **after** either `adDismissed` or `adViewed`, depending on player actions. This function should be used to resume game flow. For example, use to unmute the sound and start the next level. |\n| `adBreakDone` | function | **(OPTIONAL)** Always called as the last step in an `adBreak()`, even if there was no ad shown. Function takes as argument a `placementInfo` object defined as follows: { breakType: '\u003ctype\u003e', breakName: '\u003cname\u003e', breakFormat: 'interstitial|reward', breakStatus: 'error|noAdPreloaded|...|viewed', } See [`adBreakDone` and `placementInfo()`](#adbreakdone_and_placementinfo) for a detailed explanation of the placement info object. |\n| Rewarded placements only... |||\n| `beforeReward` | function | Called if a rewarded ad is available. The function should take a single argument--`showAdFn()` which must be called to display the rewarded ad. |\n| `adDismissed` | function | Called only for rewarded ads when the player dismisses the ad. It is only called if the player dismisses the ad before it completes. In this case the reward should not be granted. |\n| `adViewed` | function | Called only for rewarded ads when the player completes the ad and should be granted the reward. |\n\n### `adBreakDone()` `and placementInfo`\n\nIf the Ad Placement API does not have an ad to show it will not call the various\nbefore/after callbacks that you pass. However, if you provide an `adBreakDone()`\ncallback this will always be called, even if an ad is not shown. This allows you\nto do any additional work you might need to do for the placement, such as\nlogging additional analytics about the placement.\n\nThe `adBreakDone()` function takes as argument a `placementInfo` object defined\nas follows: \n\n {\n breakType: '\u003ctype\u003e',\n breakName: '\u003cname\u003e',\n breakFormat: 'interstitial|reward',\n breakStatus: 'notReady|timeout|error|noAdPreloaded|frequencyCapped|ignored|other|dismissed|viewed',\n }\n\nWhere the fields within this object have the following semantics:\n\n- `breakType` is the type argument passed to `adBreak()`\n- `breakName` is the name argument passed to `adBreak()`\n- `breakStatus` is the status of this placement and can be one of the following values:\n\n| `breakStatus` | Reason |\n|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `'notReady'` | The Ad Placement API had not initialised |\n| `'timeout'` | A placement timed out because the Ad Placement API took too long to respond |\n| `'invalid'` | The placement was invalid and was ignored--for instance there should only be one preroll placement per page load, subsequent prerolls are failed with this status |\n| `'error'` | There was a JavaScript error in a callback |\n| `'noAdPreloaded'` | An ad had not been preloaded yet so this placement was skipped |\n| `'frequencyCapped'` | An ad wasn't shown because the frequency cap was applied to this placement |\n| `'ignored'` | The user didn't click on a reward prompt before they reached the next placement, that is `showAdFn()` wasn't called before the next `adBreak()`. |\n| `'other'` | The ad was not shown for another reason. (e.g., The ad was still being fetched, or a previously cached ad was disposed because the screen was resized/rotated.) |\n| `'dismissed'` | The user dismissed a rewarded ad before viewing it to completion |\n| `'viewed'` | The ad was viewed by the user |\n\n**Note** : `adBreakDone()` is always the last callback that `adBreak()` calls.\n\nIf you use `afterAd()` to unpause your game once an ad has shown, then `adBreakDone()` will be called after your game has restarted. For things like logging analytics this may be suitable, but if you want to do additional work before your game restarts, move the logic to unpause your game from your `afterAd()` to `adBreakDone()`."]]