In-Game Rewarded Ads APIs

Conditions of Rewarded Ads

• Rewarded ads are similar to interstitial video ads with some extra API features.
• The users can opt out of the Rewarded ads by skipping or closing them. This will cause the showAdsCompletedAsync method to return a rejected promise with an error.
• The showAdsCompletedAsync method will return a resolved promise if the user watches the ad till the end.

$msstart.loadAdsAsync

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

Usage

To load Rewarded ads, use the loadAdsAsync API with isRewardedAd param set to true (false by default which is for interstitial video ads). 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(isRewardedAd).then(adInstance => {
    // Pass in boolean true for the optional parameter isRewardedAd, to fetch Rewarded ads
});

info

You can regard Rewarded ads as a special type of Interstitial video ads. The loadAdsAsync API is used to load both Rewarded ads and Interstitial video ads. The isRewardedAd parameter is used to specify the type of ad you want to load. If you do not specify the isRewardedAd parameter, the API will load an Interstitial video ad by default.

Please note that since finding an available ad bid may not happen immediately, it is recommended to call the loadAdsAsync API multiple times until an ad bid is found and loaded successfully.

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 Code	Description
REQUEST_THROTTLED	This 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_FAILURE	This 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_FAILURE	This 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.

info

Only one ad instance can be loaded at a time. If you call loadAdsAsync when you already have a loaded ad instance, you will receive a load error. This applies to both Rewarded and Interstitial video ads, which are served by the same ad server.

$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
});

Error codes

Error Code	Description
REQUEST_THROTTLED	This 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_FAILURE	This error indicates that the problem is on the client side.
SHOW_ADS_FAILURE	This 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

Both the loadAdsAsync and showAdsAsync APIs return an AdInstance object. With the showAdsAsync API, the AdInstance object also contains an additional property, showAdsCompletedAsync, which is a promise that resolves once the advertisement has completed showing.

{
    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:

• No ads should be longer than 60 seconds.
• 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.
• Reward the users for watching the ads till the end.

Development and Testing

In order to test the Rewarded ads feature, you need to add a query parameter item=flights:prg-cg-in-gm-rwd-ads to the URL. This will enable the Rewarded ads feature for your game. For example, if you are using the Dev Playground, your URL should look like this:

https://www.msn.com/en-us/play?dev-playground=GAME_URL&item=flights:prg-cg-in-gm-rwd-ads