Facebook Games

In-App Ads for Instant Games

You can monetize your game by showing ads to your players. There are currently two formats of Audience Network ads integrated with instant games: Rewarded Videos and Interstitial Ads. This section will guide you through the process of integrating Ads Monetization with your instant game.

Format Availability

PlatformInterstitialRewarded InterstitialRewarded Video

Android

✅

✅

✅

iOS

✅

✅

✅

Mobile Web

✅

✅

✅

Desktop Web

✅

✅

✅

Prerequisites

  • You have created at least one Ad Placement, within the property associated with your game in Monetization Manager.
  • You are able to test your builds on a mobile device or on Facebook.com.

Note: Audience Network is currently limited in certain regions. Check your eligibility in the Audience Network onboarding flow.

See the Audience Network 5 Steps to Monetize Instant Games guide for more information.

Configure Facebook App

Download Sample

If you have already configured your app with Monetization Manager and have created your Ad Placements, you can see the sample code below in action by downloading our demo:

Download Ads Demo (.zip)

Showing an Interstitial Ad

An interstitial is a full screen ad that appears at a natural transition point in your app. Interstitials exist in autoplay or click-to-play formats. Auto-play ads will start playing as soon as the interstitial loads; they can be skipped after 3 seconds by default. The maximum ad duration is two minutes.

The code snippet below shows an example of how to display an Interstitial ad.

For this code to work, you must first create an ad placement with the Interstitial display format. You should use a different placement for each ad unit in your app.

Preload the Ad

var preloadedInterstitial = null;

FBInstant.getInterstitialAdAsync(
  '123123123123_123123123123' // Your Ad Placement Id
).then(function(interstitial) {
  // Load the Ad asynchronously
  preloadedInterstitial = interstitial;
  return preloadedInterstitial.loadAsync();
}).then(function() {
  console.log('Interstitial preloaded');
}).catch(function(err){
  console.error('Interstitial failed to preload: ' + err.message);
});

Show the Ad

preloadedInterstitial.showAsync()
.then(function() {
  // Perform post-ad success operation
  console.log('Interstitial ad finished successfully');        
})
.catch(function(e) {
  console.error(e.message);
});

Showing a Rewarded Interstitial Ad

A rewarded interstitial is a full screen ad that gives an incentive to the user in exchange for watching the ad. These ads don't require users to opt in.

The code snippet below shows an example of how to display a Rewarded Interstitial ad.

For this code to work, you must first create an ad placement with the Rewarded Interstitial display format. Rewarded Interstitial ads are available for Facebook Gaming, Mobile Web, and Desktop Web apps. You should use a different placement for each ad unit in your app.

Preload the Ad

var preloadedRewardedInterstitial = null;

FBInstant.getRewardedInterstitialAsync(
  '123123123123_123123123123' // Your Ad Placement Id
).then(function(rewarded) {
  // Load the Ad asynchronously
  preloadedRewardedInterstitial = rewarded;
  return preloadedRewardedInterstitial.loadAsync();
}).then(function() {
  console.log('Rewarded interstitial preloaded');
}).catch(function(err){
  console.error('Rewarded interstitial failed to preload: ' + err.message);
});

Show the Ad

preloadedRewardedInterstitial.showAsync()
.then(function() {
  // Perform post-ad success operation
  console.log('Rewarded interstitial watched successfully');        
})
.catch(function(e) {
  console.error(e.message);
});

Showing a Rewarded Video Ad

Rewarded video ads are a full screen experience where users opt-in to view a video ad in exchange for something of value, such as virtual currency, in-app items, or exclusive content.

The code snippet below shows an example of how to display a Rewarded Video ad.

For this code to work, you must first create an ad placement with the Rewarded Video display format. You should use a different placement for each ad unit in your app.

Preload the ad

var preloadedRewardedVideo = null;

FBInstant.getRewardedVideoAsync(
  '456456456456_456456456456' // Your Ad Placement Id
).then(function(rewarded) {
  // Load the Ad asynchronously
  preloadedRewardedVideo = rewarded;
  return preloadedRewardedVideo.loadAsync();
}).then(function() {
  console.log('Rewarded video preloaded');
}).catch(function(err){
  console.error('Rewarded video failed to preload: ' + err.message);
});

Show the ad

preloadedRewardedVideo.showAsync()
.then(function() {
  // Perform post-ad success operation
  console.log('Rewarded video watched successfully');        
})
.catch(function(e) {
  console.error(e.message);
});

The lifecycle of ad instances

Preloading three ad instances of the same type without showing them will cause failure when you attempt to create a new ad. Once an ad is successfully loaded, the ad will be valid for 60 mins.

Here's a sample code to help you understand how it works, assuming everything is configured properly (valid ad placement IDs, etc.) and there is no network issue:

var preloadedInterstitial1 = null;
var preloadedInterstitial2 = null;
var preloadedInterstitial3 = null;
var preloadedRewardedVideo = null;

// PRELOAD PHASE
FBInstant.getInterstitialAdAsync(
  '123123123123_123123123123'
).then(function(interstitial) {
  // This should get called, meaning you now have 1 ad instance.
  preloadedInterstitial1 = interstitial;
  return preloadedInterstitial1.loadAsync();
}).then(function() {
  // This should get called unless we do not have ads to serve.
  console.log('Interstitial 1 preloaded')
}).catch(function(err){
  // This would be called only if we do not have ads to serve.
  // The error would then be ADS_NO_FILL.
  // You can try to reload the ad after some time (ideally over 30 seconds).
  // If you get ADS_NO_FILL 3 times in a row, the instance will be disabled.
  console.error('Interstitial 1 failed to preload: ' + err.message);
  // You can try to reload after 30 seconds (2nd attempt)
  setTimeout(function () { handleAdsNoFill(preloadedInterstitial1, 2); }, 30 * 1000);
});

// Here is how the function to handle ADS_NO_FILL would look like
function handleAdsNoFill (adInstance, attemptNumber) {
  if (attemptNumber > 3) {
    // You can assume we will not have to serve in the current session, no need to try
    // to load another ad.
    return;
  } else {
    adInstance.loadAsync().then(function() {
      // This should get called if we finally have ads to serve.
      console.log('Interstitial preloaded')
    }).catch(function(err){
      console.error('Interstitial failed to preload: ' + err.message);
      // You can try to reload after 30 seconds
      setTimeout(function () {
        handleAdsNoFill(adInstance, attemptNumber+1);
      }, 30 * 1000);
    });
  }
}

// As we covered ADS_NO_FILL, from now on let's assume we have ads to serve.
FBInstant.getInterstitialAdAsync(
  // You can re-use the same Ad Placement Id as long as it is of the valid type:
  // interstitial or rewarded video (here, it has to be interstitial)
  '123123123123_123123123123'
).then(function(interstitial) {
  // This should get called, meaning you now have 2 ad instances.
  preloadedInterstitial2 = interstitial;
  return preloadedInterstitial2.loadAsync();
}).then(function() {
  console.log('Interstitial 2 preloaded')
});

FBInstant.getRewardedVideoAsync(
  '456456456456_456456456456'
).then(function(rewarded) {
  // This should get called, meaning you now have 3 ad instances.
  preloadedRewardedVideo = rewarded;
  return preloadedRewardedVideo.loadAsync();
}).then(function() {
  console.log('Rewarded video preloaded')
});

FBInstant.getInterstitialAdAsync(
  '123123123123_123123123123'
).catch(function(err){
  // This should be called now because you already have 3 ad instances.
  // The error would then be ADS_TOO_MANY_INSTANCES.
  console.error('Interstitial 3 failed to preload: ' + err.message);
});

// SHOWING ADS (at a timing that makes sense in the workflow of your game)
preloadedInterstitial1.showAsync()
.then(function() {
  // This should get called, meaning you now have 2 ad instances.
  console.log('Interstitial ad 1 finished successfully');        
});

// A bit later, assuming you did not preload a new instance yet.
preloadedInterstitial2.showAsync()
.then(function() {
  // This should get called, meaning you now have 1 ad instance.
  console.log('Interstitial ad finished successfully');        
});

// A bit later, assuming you did not preload a new instance yet.
preloadedRewardedVideo.showAsync()
.then(function() {
  // This should get called, meaning you now have no ad instance.
  console.log('Rewarded video watched successfully');        
});

Best Practices and Troubleshooting

The information below is specific to Instant Games. Please also refer to our Audience Network Insights.

Time ads properly. Make sure the ads in your game don't disrupt the player experience.

Preload ads. Don't wait until last minute to request, preload and show the ad the same time. Instead, make sure that you have some AdInstances preloaded, so that when the player requests to see it, they don't have to wait too much.

Check for support. In some cases, the player's session won't support ads (e.g., if they are playing on the desktop browser). You should always check if ads are supported with FBInstant.getSupportedAPIs() before trying to request an ad.

Implement graceful handling of "No fills". Some conditions might cause the ad to not be filled. In that case, the promise will reject with an ADS_NO_FILL error message. Make sure that your game handles this gracefully, show a friendly message, and wait 30s before requesting another ad of the same type.

Test your ads before submitting. As a developer of the app, you can request ads on mobile and see that your integration is working, even before you submit your app for Audience Network review.

Track ad impressions. You can use custom events to track ad impressions when showAsync resolves.

Don't hold on to too many AdInstances. Both methods getRewardedVideoAsync or getInterstitialAdAsync return an AdInstance which can be preloaded. Preloading 3 or more AdInstances of the same type without showing them will cause subsequent attempts of creating a new AdInstance to fail. This means that calls to getRewardedVideoAsync and getInterstitialAdAsync will fail with error code ADS_TOO_MANY_INSTANCES until showAsync is called or until the player restarts Messenger.

More information