Skip to content

sud.createBannerAd ​

Creates a Banner ad object.

typescript
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;

Automatic Banner loading is subject to request frequency limits. When a limit is reached, onError reports the error code (errCode) and message (errMsg).

Parameters ​

Object object ​

PropertyTypeRequiredDescription
adUnitIdstringYesAd unit ID configured in the SUD OpenPaaS console
styleObjectYesPosition and dimensions of the maximum available Banner container
adIntervalsnumberNoInterval for automatic ad refresh, in seconds. The value must be greater than or equal to 30 (reserved parameter, not yet in effect)

object.style ​

PropertyTypeRequiredDescription
leftnumberYesMaximum container's top-left X-coordinate, in logical pixels
topnumberYesMaximum container's top-left Y-coordinate, in logical pixels
widthnumberYesMaximum available width; must be positive
heightnumberYesMaximum available height; must be positive

width / height define the maximum available area. The ad is centered horizontally and top-aligned within it, without stretching or cropping. left / top specify the area's top-left corner.

When top is 0, Android and iOS move the Banner below the top safe area when needed; leave some top spacing to avoid displaying the ad flush against the top edge.

Dimensions use logical pixels (dp on Android, pt on iOS). Query container dimensions and pixelRatio with sud.getContainerInfo. Use the logical dimensions directly for the Banner area, without multiplying or dividing by pixelRatio.

The container must accommodate the actual ad size. For example, a 300×250 ad cannot fit in a 320×100 container. If no ad candidate fits, the SDK may return -22001; see Ad Error Codes. Compare the area reserved by the game with the configured ad size, and adjust the container or ad placement configuration. A matching size still requires successful loading before display.

Return Value ​

BannerAd ad object.

BannerAd.style Actual Size ​

bannerAd.style.realWidth and bannerAd.style.realHeight are read-only actual display dimensions. Mini-game JavaScript can read them to adjust surrounding game UI or log dimensions for troubleshooting.

PropertyTypeDescription
realWidthnumberActual ad width in logical pixels; 0 before the first successful display
realHeightnumberActual ad height in logical pixels; 0 before the first successful display

style.width / style.height define the maximum available area; style.realWidth / style.realHeight describe the actual ad size. When onResize fires, the actual-size properties are available and the maximum dimensions remain unchanged.

  • To react to size changes, read the callback parameters width / height directly inside the onResize listener.
  • To query the actual size from other game logic, read bannerAd.style.realWidth / bannerAd.style.realHeight. Both are 0 before the first successful display.

Methods ​

MethodReturn valueDescription
show()Promise<void>Requests that the ad be shown
hide()Promise<void>Hides the ad
destroy()voidDestroys the ad; the object cannot be reused

The Promises returned by show() and hide() report only the method-call result. Loading or display failures are reported through onError.

Events ​

MethodDescription
onLoad(listener)Listens for a successful ad load
offLoad(listener)Removes the specified load listener
onError(listener)Listens for ad loading or display failures
offError(listener)Removes the specified error listener
onResize(listener)Listens for the first actual size after successful display and subsequent size changes
offResize(listener)Removes the specified resize listener

onError Callback Parameters ​

The onError listener receives the following object:

PropertyTypeDescription
errCodenumberSee ad error codes
errMsgstringError message

onResize Callback Parameters ​

The onResize listener receives the following object:

PropertyTypeDescription
widthnumberActual ad width in logical pixels, matching style.realWidth
heightnumberActual ad height in logical pixels, matching style.realHeight

The first size notification follows an actual successful display; subsequent notifications occur only when the actual size changes. Loading without display, display failure, identical sizes, and position-only changes do not trigger a notification. Resolving the show() Promise does not mean the ad has actually displayed. Call show() after onLoad; do not wait for onResize to display the ad.

Example ​

Create the Banner on scene entry and display it after onLoad. 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, use the actual game layout; see layout notes.

The height of 100 in this example only demonstrates the layout. Reserve space according to the actual ad size; it cannot accommodate an ad with a height of 250.

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

// adIntervals is an optional parameter; it is a reserved parameter not yet in effect.
const adIntervals = 30;

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)),
    },
    adIntervals,
});

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);

Bind onBannerSceneExit() to scene exit. For the complete flow, see game developer examples.