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() 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().