Manually sequence game loading with onReady

When the page containing your game first loads there are a number of asynchronous events taking place.

Your game logic loads, the ads tag loads, the Ad Placement API starts initialising, and ads can be preloaded. As a result, if you call adBreak() very soon after page load, there is a chance that the API may not have initialized or that ads have not finished preloading. If the API has not initialized the call will fail, and if you've registered an adBreakDone() callback, the breakStatus will be set to notReady.

If you need to synchronize your game logic with the initialization of the Ad Placement API, you can use the onReady() callback to adConfig().

onReady() is called by the Ad Placement API when:

• the ad's tag has loaded,
• the Ad Placement API has loaded and initialized, and
• ads have finished preloading—if you requested preloading using adConfig()

At this point the Ad Placement API is fully initialized. You can call adBreak(), and it won't return a notReady status. But as always adBreak() may still not show an ad (for example, there wasn't an ad available).

Here's an example that shows the use of onReady():

...
<script>
    window.adsbygoogle = window.adsbygoogle || [];
    var adBreak = adConfig = function(o) {adsbygoogle.push(o);}
    ...
    function init() {
      // Game start logic, show loading screen
      adConfig({
        preloadAdBreaks: 'on',
        onReady: showAd
      });
      // Don't start the gameplay just yet, keep loading.
    }

    function showAd() {
      // Show an ad
      adBreak({
        type: 'start',
        adBreakDone: startGame,  // always called, unblocks the game logic
        ...
      });
    }
    ...
</script>

Note: the most common use case to call adBreak() very soon after page load is to implement a preroll. We strongly recommend you use a preroll placement type rather than trying to create your own using the methods described here.

preroll automatically implements all of the required preloading and timeout logic. If you use a preroll with your game, you don't need to use onReady(). Learn more about preroll

Timeouts

onReady() is not guaranteed to be called if the Ad Placement API initialisation is delayed or fails to load entirely. To ensure your game starts in a timely fashion, you may want to set up a timeout. If you receive the onReady()callback, then you can call adBreak() to place the ad, otherwise you can skip the ad call and proceed to load your game.

The following example includes a timeout—and is similar to the logic implemented by a preroll placement:

...
<script>
    window.adsbygoogle = window.adsbygoogle || [];
    var adBreak = adConfig = function(o) {adsbygoogle.push(o);}
    ...
    function init() {
        // Game start logic
        let adConfigPromise =
            new Promise((resolve, reject) => adConfig({
                preloadAdBreaks: 'on',
                onReady: () => resolve(true)
            }));
        let timeoutPromise =
            new Promise((resolve, reject) => {
                setTimeout(() => {
                    resolve(false);
                }, 2000);
            });
        // Whatever happens first resolves this promise.
        Promise.race([
            adConfigPromise,
            timeoutPromise
        ]).then((shouldShowPreRoll) => {
            if (shouldShowPreRoll) {
                showPreRoll();
            } else {
                startGame();
            }
        });
    }

    function showPreRoll() {
      // Show ad
      adBreak({
          type: 'start',
          adBreakDone: startGame, // always called, unblocks the game logic
          ...
      });
    }
    ...
</script>