Skip to main content

In-Game Interstitial Ads APIs

In-game interstitial ads are video ads that pop up and cover the game screen. They can load and play at any point, except during the hold or cooldown periods.

$msstart.loadAdsAsync​

The loadAdsAsync API is used to find an available ad bid and load it as an ad instance. The API works asynchronously and returns a promise that resolves with an AdInstance object once an ad bid has been found and loaded successfully.

Usage​

To use the loadAdsAsync API, simply call the function and it will return a promise that resolves to an AdInstance object. This AdInstance contains the instanceId property, which is required to make a call to the showAdsAsync API. The instanceId property uniquely identifies the ad instance.

$msstart.loadAdsAsync().then(adInstance => {
    // Use the adInstance.instanceId to make a call to showAdsAsync
});

Please note that finding an available ad bid may not always be possible, so you may have to try again several times.

Error codes​

Error CodeDescription
REQUEST_THROTTLEDThis error is returned when the loadAdsAsync API is called right after LOAD_ADS_FAILURE error. This indicates that $msstart.loadAdsAsync is in a cooldown period and during this period, the API will return this same error until the cooldown period is over.
LOAD_ADS_CLIENT_FAILUREThis error is returned when there is a client-side error while loading the ad bid. This means that the request hasn't even reached the server.
LOAD_ADS_FAILUREThis error is returned when the ad server fails to find an ad bid.
caution

Please ensure that you address these errors appropriately and follow the recommended actions specified in each error message.

$msstart.showAdsAsync​

The showAdsAsync API is used to show an advertisement using the instanceId of a loaded ad instance. The API returns an AdInstance object with an additional property, showAdsCompletedAsync, which notifies the completion of showing the advertisement.

Note that we strongly recommend making a load request with $msstart.loadAdsAsync() well in advance of calling $msstart.showAdsAsync() and ensure that the ad is pre-fetched, loaded and ready to be shown before calling $msstart.showAdsAsync(). By doing so, you could eliminate any potential latency and overhead in showing the ad.

Usage​

To use the showAdsAsync API, you need to have a loaded ad instance and the instanceId of that instance. Once you have that, you can call the showAdsAsync function and pass in the instanceId as a parameter.

$msstart.showAdsAsync(adInstance.instanceId).then(adInstance => {
    // Use the adInstance.showAdsCompletedAsync to be notified of the completion of showing the advertisement
});

Hold Periods​

Please note that there currently are two different hold periods during which you would receive a failure error if you make a call to the showAdsAsync API:

  • The first 30 seconds after the game starts
  • The 30 seconds following the end of an advertisement
caution

The purpose of these hold periods is to ensure that users only see an ad between game sessions, which is a requirement that games should also fulfill regardless of these hold periods.

Error codes​

Error CodeDescription
REQUEST_THROTTLEDThis error is returned when the ShowAdsAsync API is called during the hold periods. This indicates that $msstart.loadAdsAsync is in a hold period and during this period, the API will return this same error until the hold period is over.
SHOW_ADS_CLIENT_FAILUREThis error indicates that the problem is on the client side.
SHOW_ADS_FAILUREThis error means that something went wrong before the ad could play.
caution

Please ensure that you address these errors appropriately and follow the recommended actions specified in each error message.

AdInstance Object​

The loadAdsAsync and showAdsAsync APIs both return an AdInstance object. However, the showAdsAsync API also adds a showAdsCompletedAsync property to the AdInstance object. This property returns a promise that resolves to a new AdInstance object with the same instanceId value when the ad finishes playing or the user skips it. If the ad encounters an error after it starts playing, the promise will reject with an error.

{
    instanceId: 'unique-ad-instance-id',
    showAdsCompletedAsync?: Promise
}

Backfill ads​

A backfill ad, also referred to as a "filler ad" or "remnant ad," is an advertisement displayed or played when the primary ad inventory is unavailable or fails. By default, we provide backfill ads for every ad request you make. However, in circumstances where our ad server fails to find an ad bid, you can backfill with your own ads. Please keep in mind that you should only use your own backfill ads when our ad server is unable to find an ad bid using $msstart.loadAdsAsync() or when the ad fails during or after calling $msstart.showAdsAsync(). Additionally, please ensure that the following guidelines are met for your backfill ads:

  • Ads allow users to mute or unmute the sound.
  • Ads longer than 30 seconds have a skip option.
  • No ads are shown in the first 30 seconds after the game launches, and ads are at least 30 seconds apart from each other. (These are the same rules as the hold period for interstitial ads)
  • Ads have a clear and visible label or indicator that they are ads. They are not confusing or misleading as part of the game content.
  • Ads have graceful error handling. No ads freeze or prevent users from returning to their games.

In some cases, you may need a consent string to show backfill ads. A consent string is a value that indicates the user’s consent preferences for data collection and use. You can use the getConsentStringAsync API, which returns a promise that resolves to the consent string value.