# adBreak()

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()`](https://developers.google.com/ad-placement/apis/adbreak#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()`.