sud.createBannerAd

Creates a banner ad component. Each call to this method returns a brand-new banner ad instance. The ad loads automatically after creation; load success is reported through BannerAd.onLoad(), and load or display failures are reported through BannerAd.onError().

createBannerAd(params: {
    adUnitId: string;
    style: {
        left: number;
        top: number;
        width: number;
        height: number;
    };
    /** Interval for automatic ad refresh, in seconds. The value must be greater than or equal to 30 (reserved parameter, not yet in effect) */
    adIntervals?: number;
}): BannerAd;

Banner auto-loading is rate-limited (currently triggered by repeated requests within 10 seconds). When the limit is hit, BannerAd.onError() returns the error code (errCode) and message (errMsg).

Parameters

Object object

Property	Type	Default	Required	Description
adUnitId	string		Yes	Ad unit ID configured in the SUD OpenPaaS console
style	Object		Yes	Position and size of the maximum available container for the banner ad
adIntervals	number		No	Interval for automatic ad refresh, in seconds. The value must be greater than or equal to 30 (reserved parameter, not yet in effect)

Structure of object.style

Property	Type	Default	Required	Description
left	number		Yes	X coordinate of the top-left corner of the maximum available container, in logical pixels
top	number		Yes	Y coordinate of the top-left corner of the maximum available container, in logical pixels
width	number		Yes	Maximum available width, must be greater than 0
height	number		Yes	Maximum available height, must be greater than 0

width / height define the maximum available area. The ad is centered horizontally and aligned to the top within that area, without stretching or cropping; left / top are the coordinates of its top-left corner.

Sizes are in logical pixels (dp on Android, pt on iOS). Container dimensions and pixelRatio are available from sud.getContainerInfo; set the banner area with logical width and height directly, with no need to multiply or divide by pixelRatio. The actual size reported by BannerAd.onResize() needs no conversion either.

Return Value

BannerAd

Banner ad component.

style.width / style.height define the maximum available area, while style.realWidth / style.realHeight are the read-only actual display size and are 0 until the first successful display. Read the actual size when BannerAd.onResize() fires; the maximum available width and height stay unchanged.

Example Code

Create the banner ad on scene entry and display it after the BannerAd.onLoad() notification. This full-screen game example uses sud.getContainerInfo to reserve a top area as wide as the container and at most 100 logical pixels high. Keep game UI outside that area. For split-screen or embedded games, determine the reserved area from the actual game layout.

const { containerWidth, containerHeight } = sud.getContainerInfo();

const bannerAd = sud.createBannerAd({
    adUnitId: 'adunit-xxxxxxxx',
    style: {
        left: 0,
        top: 0,
        // Use logical dimensions directly for the reserved area.
        width: Math.floor(containerWidth),
        height: Math.min(100, Math.floor(containerHeight)),
    },
    // Optional parameter; reserved, not yet in effect
    adIntervals: 30,
});

let disposed = false;
let showRequested = false;

function onLoad() {
    if (disposed || showRequested) return;
    showRequested = true;
    bannerAd.show().catch(onError);
}

function onError(err) {
    if (disposed) return;
    console.error('Banner ad failed', err);
    onBannerSceneExit();
}

function onResize({ width, height }) {
    if (disposed) return;
    // Matches bannerAd.style.realWidth / realHeight; use it to adjust surrounding game UI.
    console.log('Banner actual size', width, height);
}

function onBannerSceneExit() {
    if (disposed) return;
    disposed = true;
    bannerAd.offLoad(onLoad);
    bannerAd.offError(onError);
    bannerAd.offResize(onResize);
    bannerAd.destroy();
}

bannerAd.onLoad(onLoad);
bannerAd.onError(onError);
bannerAd.onResize(onResize);

The reserved area is as wide as the container, and the ad is centered horizontally and top-aligned within it, so it appears centered on screen. Bind onBannerSceneExit() to the scene exit and call it even if the ad is still loading; once destroyed, a late load callback can no longer call show().