H5 Games Ads API: The Ultimate Integration Guide

The era of Flash is long gone, but the era of HTML5 web games is booming. With platforms like Poki, CrazyGames, and Telegram Gaming seeing massive traffic in 2026, developers are flocking back to the web.

However, monetizing a web game is tricky. Traditional AdSense banners are intrusive; they shift your layout (CLS issues) and annoy players. What you need are Mobile-style ads on the web: Full-screen Interstitials and Rewarded Videos.

Google's solution is the H5 Games Ads API (formerly known as AFG - AdSense for Games). It is a specialized SDK designed specifically for the Canvas/WebGL environment. In this guide, I will walk you through a production-ready implementation that handles audio focus, game pausing, and policy compliance.

1. The Head Script: Configuration

The first step is adding the SDK to your `index.html`. This is not the standard AdSense snippet. It accepts specific parameters that control ad frequency.

Key Parameters Explained

Parameter	Function
data-ad-breakout	If set to "on", the ad will try to break out of the iframe to cover the full screen. Essential for portals like CrazyGames.
data-ad-frequency-hint	Tells Google the minimum time between ads. If you request ads every 5 seconds, Google will ignore you. Setting this to "30s" helps fill rates.
data-ad-test	Set to "on" during development. NEVER click your own live ads; you will get banned. Use test mode.

2. Initializing the API

The API creates a global function usually called `adBreak`. It is best practice to wrap this in a safe initialization function to ensure the SDK is loaded before you call it.

// GameAds.js

// 1. Ensure the array exists
window.adsbygoogle = window.adsbygoogle || [];

// 2. Create the wrapper function
const adConfig = function(o) { 
    window.adsbygoogle.push(o); 
}

// 3. Initialize properly
function initAds() {
    adConfig({
        preloadAdBreaks: 'on',
        sound: 'on', // Tells Google the game has sound
        onReady: () => {
            console.log("Ads API is ready!");
        }
    });
}
            

3. Implementing Interstitial Ads (Between Levels)

Interstitials are forced ads shown at natural breaks in gameplay (e.g., Game Over, Level Complete).

Crucial Logic: You must pause your game logic and audio before the ad starts, and resume it after the ad closes.

function showInterstitial() {
    adConfig({
        type: 'start', // or 'next', 'browse'
        name: 'level_complete_ad',
        
        // Triggers BEFORE ad shows
        beforeAd: () => { 
            console.log("Pausing Game...");
            AudioManager.muteAll(); // Important!
            GameEngine.pause();
        },

        // Triggers AFTER ad closes
        afterAd: () => { 
            console.log("Resuming Game...");
            AudioManager.unmuteAll();
            GameEngine.resume();
        },

        // Triggers if ad loads, fails, or is skipped
        adBreakDone: (placementInfo) => {
            console.log("Ad result: " + placementInfo.breakStatus);
            // placementInfo.breakStatus can be:
            // 'viewed', 'dismissed', 'timeout', 'error', 'notReady'
        }
    });
}
            

4. Implementing Rewarded Ads (Value Exchange)

Rewarded ads are the gold standard. They have higher eCPMs because users actually watch them. Use these for "Revive," "Double Coins," or "Extra Time."

function showRewardedAd(onRewardGranted) {
    adConfig({
        type: 'reward',
        name: 'revive_player',
        
        beforeAd: () => { 
            AudioManager.muteAll();
            GameEngine.pause();
        },
        
        afterAd: () => { 
            AudioManager.unmuteAll();
            GameEngine.resume();
        },
        
        adBreakDone: (placementInfo) => {
            // ONLY grant reward if status is 'viewed'
            if (placementInfo.breakStatus === 'viewed') {
                console.log("User watched the whole video!");
                onRewardGranted();
            } else {
                console.log("User closed ad early or no ad available.");
                // Do NOT grant reward
            }
        }
    });
}
            

5. Advanced: Handling Audio Focus

A requirement of the H5 Ads policy is that no game sound can play while an ad is visible.

Browsers behave differently regarding auto-play audio. When an ad finishes, the browser might block your game from automatically resuming audio until the user interacts with the page again.

Best Practice: In your `afterAd` callback, do not just blindly call `Audio.play()`. Instead, check if the browser allows it, or wait for the next user input (touch/click) to resume the soundtrack.

6. Troubleshooting Common Errors

Status	Meaning	Fix
notReady	Google has no ad inventory available for this user right now.	Do nothing. Just resume the game smoothly. Do not show an error to the user.
frequencyCapped	You called ads too often (e.g., twice in 10 seconds).	Respect the `data-ad-frequency-hint` setting.
timeout	The user's internet is too slow to load the video asset.	Resume game immediately.

Conclusion

Integrating the H5 Games Ads API is significantly more complex than dropping a banner on a blog, but the revenue potential is 10x higher. By respecting the user experience—pausing audio correctly, not spamming ads, and offering valuable rewards—you can create a sustainable income stream from your web games.

At Boomie Studio, we use a wrapper class for this API that handles the "Test Mode" toggle automatically based on the domain (localhost vs production). This prevents us from ever accidentally viewing live ads during development.

---

Frequently Asked Questions (FAQ)

Q: Can I use this with Unity WebGL?
A: Yes. You need to create a `.jslib` plugin in Unity to communicate between C# and the JavaScript `adConfig` function we wrote above.

Q: What is the fill rate?
A: It varies by region. Tier 1 countries (US, UK) have high fill rates. If you are getting low fill rates, ensure your `ads.txt` file is correctly set up on your root domain.

Q: Does this work on iPhone Safari?
A: Yes, the H5 API is fully compatible with mobile browsers, including Safari on iOS and Chrome on Android.