adBreak()
Stay organized with collections
Save and categorize content based on your preferences.
Function signature:
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() parameters
| Name |
Type |
Description |
| All placement types |
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
|
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. |
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. |
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. |
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: '<type>',
breakName: '<name>',
breakFormat: 'interstitial|reward',
breakStatus: 'error|noAdPreloaded|...|viewed',
}
See adBreakDone and placementInfo() for a detailed explanation of the placement info object. |
| Rewarded placements only... |
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. |
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. |
adViewed |
function |
Called only for rewarded ads when the player completes the ad and should be granted the reward. |
adBreakDone() and placementInfo
If the Ad Placement API does not have an ad to show it will not call the various
before/after callbacks that you pass. However, if you provide an adBreakDone()
callback this will always be called, even if an ad is not shown. This allows you
to do any additional work you might need to do for the placement, such as
logging additional analytics about the placement.
The adBreakDone() function takes as argument a placementInfo object defined
as follows:
{
breakType: '<type>',
breakName: '<name>',
breakFormat: 'interstitial|reward',
breakStatus: 'notReady|timeout|error|noAdPreloaded|frequencyCapped|ignored|other|dismissed|viewed',
}
Where the fields within this object have the following semantics:
breakType is the type argument passed to adBreak()breakName is the name argument passed to adBreak()breakStatus is the status of this placement and can be one of the
following values:
breakStatus |
Reason |
'notReady' |
The Ad Placement API had not initialised |
'timeout' |
A placement timed out because the Ad Placement API took too long to respond |
'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 |
'error' |
There was a JavaScript error in a callback |
'noAdPreloaded' |
An ad had not been preloaded yet so this placement was skipped |
'frequencyCapped' |
An ad wasn't shown because the frequency cap was applied to this placement |
'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(). |
'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.) |
'dismissed' |
The user dismissed a rewarded ad before viewing it to completion |
'viewed' |
The ad was viewed by the user |
Note: adBreakDone() is always the last callback that adBreak() calls.
If 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().
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2023-12-05 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2023-12-05 UTC."],[[["\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()`."]]