Skip to content

Game Developer Examples ​

This page connects ads to game scenes, buttons, and game flow. Complete app advertising integration on both platforms first, then run the game script in SUD OpenPaaS Runtime. A normal browser does not automatically provide sud.

Replace each YOUR_*_AD_UNIT_ID with a SUD OpenPaaS ad unit ID for that format. createBannerExample, createFullscreenExample, and the scene functions below are game-side sample functions, not new SDK APIs. Copy the two helpers into your game script and select the formats you need.

When to Call ​

Game eventGame-side action
Enter an ad-enabled sceneCreate the instance and register listeners; Banner loads automatically, while full-screen formats require load()
Receive onLoadMark the ad as available
Finish a level, click the reward button, or reach the startup display pointCall the sample object's show()
Temporarily cover the BannerCall setVisible(false); pass true to restore it
Leave the corresponding sceneCall dispose() to remove listeners and destroy the instance

A resolved load() Promise only means the loading call was accepted. Mark the ad as loaded in onLoad. The full-screen sample's show() returns false if the ad is not ready and does not queue a later display. A true result only means the display call was issued; actual failures still arrive through onError.

Each full-screen instance is shown at most once. It is cleaned up on close or failure; create a new instance for another ad. Connect the scene-exit functions to your engine's actual lifecycle instead of calling them immediately after creation.

API: sud.createBannerAd.

onResize only receives actual dimensions; it does not display an ad or replace onLoad.

javascript
function createBannerExample(adUnitId, style, adIntervals) {
    // adIntervals is optional and not yet in effect
    const ad = sud.createBannerAd({ adUnitId, style, adIntervals });
    if (!ad) {
        throw new Error('Banner ad is unavailable in this runtime');
    }

    let active = true;
    let loaded = false;
    let visible = true;

    function dispose() {
        if (!active) return;
        active = false;
        ad.offLoad(onLoad);
        ad.offError(onError);
        ad.offResize(onResize);
        ad.destroy();
    }

    function onError(err) {
        if (!active) return;
        console.error('Banner ad failed', err);
        dispose();
    }

    function onLoad() {
        if (!active || loaded) return;
        loaded = true;
        if (visible) ad.show().catch(onError);
    }

    function onResize({ width, height }) {
        if (!active) return;
        console.log('Banner actual size', width, height);
    }

    function setVisible(value) {
        if (!active || visible === value) return;
        visible = value;
        if (!loaded) return;
        if (visible) {
            ad.show().catch(onError);
        } else {
            ad.hide().catch(onError);
        }
    }

    ad.onError(onError);
    ad.onLoad(onLoad);
    ad.onResize(onResize);
    return { setVisible, dispose };
}

Create the Banner on scene entry with the maximum available logical width and height (dp on Android, pt on iOS). The ad is centered horizontally and top-aligned within that area. The third parameter adIntervals is optional and is not yet in effect.

Use sud.getContainerInfo to query container dimensions and the pixel ratio. Fill in style below using the game's actual reserved area without multiplying by pixelRatio. The actual dimensions from onResize need no further conversion either.

javascript
const banner = createBannerExample('YOUR_BANNER_AD_UNIT_ID', {
    left: 20,
    top: 100,
    width: 320,
    height: 100,
}, 30);

function onOverlayOpened() {
    banner.setVisible(false);
}

function onOverlayClosed() {
    banner.setVisible(true);
}

function onBannerSceneExit() {
    banner.dispose();
}

Call onBannerSceneExit() even while loading. A late load callback will not call show() after disposal. Hiding during loading preserves the hidden state when loading completes.

Full-screen Loading and Cleanup ​

Use the following helper for interstitial and rewarded video ads. Copy it into your game script and call show() at the intended display point and dispose() on scene exit.

javascript
function createFullscreenExample(ad, onClosed) {
    if (!ad) {
        throw new Error('Full-screen ad is unavailable in this runtime');
    }

    let active = true;
    let loaded = false;
    let showRequested = false;

    function dispose() {
        if (!active) return;
        active = false;
        ad.offLoad(onLoad);
        ad.offError(onError);
        ad.offClose(onClose);
        ad.destroy();
    }

    function onError(err) {
        if (!active) return;
        console.error('Full-screen ad failed', err);
        dispose();
    }

    function onLoad() {
        if (active) loaded = true;
    }

    function onClose(result) {
        if (!active) return;
        dispose();
        if (onClosed) onClosed(result);
    }

    function show() {
        if (!active || !loaded || showRequested) return false;
        showRequested = true;
        ad.show().catch(onError);
        return true;
    }

    ad.onError(onError);
    ad.onClose(onClose);
    ad.onLoad(onLoad);
    ad.load().catch(onError);
    return { show, dispose };
}

Interstitial: Display After a Level ​

API: sud.createInterstitialAd. Create and load on level entry, call onLevelFinished() when the level ends, and call onInterstitialSceneExit() on scene exit.

javascript
const interstitial = createFullscreenExample(
    sud.createInterstitialAd({ adUnitId: 'YOUR_INTERSTITIAL_AD_UNIT_ID' }),
    () => console.log('Interstitial closed'),
);

function onLevelFinished() {
    if (!interstitial.show()) {
        console.log('Interstitial is not ready; continue the game');
    }
}

function onInterstitialSceneExit() {
    interstitial.dispose();
}

Rewarded Video: Display After User Choice ​

API: sud.createRewardedVideoAd. Create and load on reward-scene entry. Call onRewardButtonClick() only after the user clicks the watch-ad button; loading alone does not display the ad.

javascript
const rewarded = createFullscreenExample(
    sud.createRewardedVideoAd({
        adUnitId: 'YOUR_REWARDED_AD_UNIT_ID',
        // The following are optional and not yet in effect
        multiton: true,
        disableFallbackSharePage: false,
    }),
    (result) => {
        console.log('Reward result', result);
        if (result?.isEnded === true) {
            console.log('Reward condition met');
            // Apply the game's reward once here.
        }
    },
);

function onRewardButtonClick() {
    if (!rewarded.show()) {
        console.log('Rewarded ad is not ready; keep the user in the game');
    }
}

function onRewardSceneExit() {
    rewarded.dispose();
}

isEnded in onClose indicates whether the ad met the reward condition. Grant the reward only when isEnded === true, at most once per display.

Integration Checks ​

Check load success, load failure, scene exit, and repeated clicks in the game. For Banner, also check hiding during loading, restoring visibility, actual-size callbacks, and placement. For rewarded video, check both reward outcomes and ensure each display grants at most one reward.