Skip to main content

In-Game Display Ads APIs

caution

Your team must be signed for monetization and be manually onboarded to use this API. If you do not have permissions and believe you should be, please let us know.

$msstart.showDisplayAdsAsync​

The showDisplayAdsAsync API is used to show a display ad in the gameplay window. The display ad will be placed using the size and positioning corresponding to the 'displayAdPlacement' parameter. The API will attempt to load and render the ad asynchronously, and will return a success or failure code.

Display Ad Placements​

  • The displayAdPlacement parameter is a string following the schema: {position}:{width}x{height}. However, not just any values may be used here. You must use one of the supported placement strings found below.
  • The ad shown will take up space on the screen equal to the {width} and {height} requested, plus an additional 20px height for ad attribution.
  • The ad {position} will denote which edge of the screen to place the ad, padded 20px, centered between the two adjacent sides.
    • (e.g. If "right" position is requested, the ad will be placed 20px from the right edge of the gameplay screen, vertically centered)

ALL Supported Values for displayAdPlacement​

  • top:728x90
  • top:970x250
  • left:300x250 | right:300x250 | topleft:300x250 | topright:300x250 | bottomleft:300x250 | bottomright:300x250
  • left:300x600 | right:300x600
  • top:320x50 | right:320x50 | bottom:320x50 | left:320x50
  • left:160x600 | right:160x600

Conditions​

  • The displayAdPlacement parameter must match exactly (case-sensitive) one of the supported values in the above Display Ad Placement list. If it does not, the API will return an error response.
  • You must wait 5 seconds between individual showDisplayAdsAsync API calls. If a subsequent call is made too soon, the API will return an error response.
  • If the gameplay window is insufficient size to render the requested ad size comfortably, the API will return an error response.
  • An ad size may potentially receive no bid. If this happens, the API will return an error response.
  • Our larger ad sizes (970x250 and 300x600) may have low fill rate, and can automatically fallback to smaller size. 970x250 can fallback to 728x90, and 300x600 can fallback to 300x250. In this case, the API will still return success response.
  • Only one ad may be visible at a time. If a new placement is requested, the old ad will be hidden.

Usage​

To use the showDisplayAdsAsync API, call the function with one of the approved displayAdPlacement values

$msstart.showDisplayAdsAsync(displayAdPlacement).then(response => {
    // Returns string indicating success
});

Please note that it may take up to a few seconds to get a response. This request will wait for our ad provider to load and render an ad before returning a success or fail response.

$msstart.hideDisplayAdsAsync​

The hideDisplayAdsAsync API is used to hide any visible in-game display ad.

Conditions​

  • If no ads are currently visible, the API will return an error response. hideDisplayAdsAsync should only be called if showDisplayAdsAsync returned a successful response.

Usage​

To use the hideDisplayAdsAsync API, you will simply make a call with no parameter. The api will hide any visible ad instantly, and return a response.

$msstart.hideDisplayAdsAsync().then(response => {
    // Returns string indicating success if ad was hidden successfully
});