H5 Gaming Interstitial

How to implement H5 gaming interstitial ads using Fuse

Overview

H5 gaming interstitials are full-screen ads that appear at natural transition points in HTML5 games, such as between game levels or after completing a challenge. These ads provide a non-disruptive way to monetize gaming content while maintaining a good user experience.

Note: H5 Gaming Interstitial is an opt-in feature offered by Google Ad Manager/Ad Exchange (GAM/AdX). Publishers must be explicitly approved for this feature before it can run.

How it Works

The H5 interstitial format uses Google Publisher Tag’s GAME_MANUAL_INTERSTITIAL out-of-page format. Fuse provides a simple API to:

  1. Register the ready, closed, and empty callbacks
  2. Register and load an interstitial ad
  3. Receive either the ready callback (fill) or the empty callback (no fill); exactly one fires per ad request
  4. Call displayH5Interstitial() to display the ad
  5. Receive the closed callback when the ad is closed

Important: Always register the onH5InterstitialReady, onH5InterstitialClosed, and onH5InterstitialEmpty callbacks before calling registerH5Interstitial. The ready or empty callback can fire as soon as GAM responds. If the callback is not registered yet, you will miss the event.

Configuration

Admin Panel Setup

In the Fuse admin panel, create a zone with the h5Interstitial attribute set to true. This tells Fuse to configure the zone as a gaming interstitial.

{
  "attributes": {
    "h5Interstitial": true
  }
}

API Reference

Register onH5InterstitialReady, onH5InterstitialClosed, and onH5InterstitialEmpty before calling registerH5Interstitial. The APIs below are listed in the order they should be called.

fusetag.onH5InterstitialReady(callback)

Sets a callback function to be called when the interstitial ad is ready to display. Register this before calling registerH5Interstitial — the ready callback can fire as soon as the ad loads, and a callback registered after that point will not be invoked.

Parameters:

  • callback (function): A callback function that receives the zone code as a parameter

Example:

fusetag.que.push(function() {
  fusetag.onH5InterstitialReady(function(zoneCode) {
    console.log('Ad is ready:', zoneCode);
    // Enable your "Next Level" button or similar UI
  });
});

fusetag.onH5InterstitialClosed(callback)

Sets a callback function to be called when the user closes the interstitial ad. Register this before calling registerH5Interstitial.

Parameters:

  • callback (function): A callback function that receives the zone code as a parameter

Example:

fusetag.que.push(function() {
  fusetag.onH5InterstitialClosed(function(zoneCode) {
    console.log('Ad was closed:', zoneCode);
    // Continue your game or advance to next level
  });
});

fusetag.onH5InterstitialEmpty(callback)

Sets a callback function to be called when GAM returns no ad for the registered slot. onH5InterstitialReady and onH5InterstitialEmpty are mutually exclusive per ad request: exactly one fires. Register this before calling registerH5Interstitial.

Only one callback can be registered — a second call replaces the previous callback and fires a console.error ([H5-INTERSTITIAL]: onH5InterstitialEmpty: replacing existing callback — only the latest registration will fire. Register a single dispatcher if you need to fan out.) so accidental double-registration is loud. The same guard applies to onH5InterstitialReady and onH5InterstitialClosed.

Parameters:

  • callback (function): A callback function that receives the zone code as a parameter

Example:

fusetag.que.push(function() {
  fusetag.onH5InterstitialEmpty(function(zoneCode) {
    console.log('No ad fill for:', zoneCode);
    // Continue your game without showing an interstitial
  });
});

fusetag.registerH5Interstitial(zoneCode)

Registers and loads an H5 interstitial ad for the specified zone code. Call this after registering the ready, closed, and empty callbacks.

Parameters:

  • zoneCode (string): The zone code configured in the Fuse admin panel

Example:

fusetag.que.push(function() {
  fusetag.registerH5Interstitial('my_test_h5_interstitial');
});

fusetag.displayH5Interstitial()

Triggers the display of the interstitial ad. Call this after the interstitial is ready (for example, after onH5InterstitialReady fires) to make the H5 gaming interstitial visible.

Parameters:

  • None

Example:

fusetag.que.push(function() {
  fusetag.displayH5Interstitial();
});

Implementation Example

Here’s a complete example of implementing an H5 gaming interstitial:

<!DOCTYPE html>
<html>
<head>
  <title>My Game</title>
  <script async src="https://cdn.fuseplatform.net/publift/tags/2/YOUR_ACCOUNT/fuse.js"></script>
</head>
<body>
  <div id="game-container">
    <h1>Level <span id="level">1</span></h1>
    <button id="next-level" onclick="showInterstitial()">Next Level</button>
  </div>

  <script>
    const fusetag = window.fusetag || (window.fusetag = { que: [] });
    let currentLevel = 1;
    let adReady = false;

    fusetag.que.push(function() {
      // Set up callbacks
      fusetag.onH5InterstitialReady(function(zoneCode) {
        console.log('H5: Interstitial ready:', zoneCode);
        adReady = true;
      });

      fusetag.onH5InterstitialEmpty(function(zoneCode) {
        console.log('H5: No fill for', zoneCode, '- advancing without ad');
        advanceLevel();
      });

      fusetag.onH5InterstitialClosed(function(zoneCode) {
        console.log('H5: Interstitial closed:', zoneCode);
        advanceLevel();
      });

      // Register the interstitial
      fusetag.registerH5Interstitial('test_h5_interstitial');
    });

    function showInterstitial() {
      if (!adReady) {
        console.log('H5: Ad not ready yet');
        return;
      }

      fusetag.que.push(function() {
        fusetag.displayH5Interstitial();
      });
    }

    function advanceLevel() {
      currentLevel++;
      document.getElementById('level').textContent = currentLevel;

      // Register a new interstitial for the next level
      adReady = false;
      fusetag.que.push(function() {
        fusetag.registerH5Interstitial('test_h5_interstitial');
      });
    }
  </script>
</body>
</html>

Live Example

Best Practices

  1. Timing: Show interstitials at natural break points in your game, such as between levels or after completing a challenge. Avoid interrupting active gameplay.

  2. Frequency: Don’t show interstitials too frequently. Google recommends limiting interstitial frequency to maintain a positive user experience.

  3. User Feedback: Provide visual feedback to users about when an ad is loading or will be shown.

  4. Error Handling: Always check if the ad is ready before attempting to display it. The ad may not load if there’s no available inventory or if there’s a network issue.

  5. Progressive Enhancement: Ensure your game works even if ads fail to load. Don’t make game progression dependent on ad display.

Troubleshooting

Ad doesn’t display:

  • Verify the zone is configured with h5Interstitial: true in the admin panel
  • Check that registerH5Interstitial was called before attempting to display
  • Ensure the zone code matches the configuration
  • Check browser console for errors

Callback not firing:

  • Ensure onH5InterstitialReady, onH5InterstitialClosed, and onH5InterstitialEmpty are registered before calling registerH5Interstitial. If you register the callback after, the ready or empty event may have already fired and your callback will never be invoked.
  • Verify all code is wrapped in fusetag.que.push()
  • Check for JavaScript errors that might prevent callback execution

Ad never appears and ready callback never fires:

  • GAM may have returned no fill for this request. Register onH5InterstitialEmpty to detect this case rather than waiting on onH5InterstitialReady indefinitely.

Ad displays at wrong time:

  • For manual gaming interstitials, the ad displays when your code calls displayH5Interstitial()
  • Only call displayH5Interstitial() after the ready callback has fired and you have confirmed the ad is ready
  • If the ad appears at the wrong time, check where displayH5Interstitial() is invoked in your game flow

See Also