sud.createBannerAd
Creates a Banner ad object.
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
| Property | Type | Required | Description |
|---|---|---|---|
| adUnitId | string | Yes | Ad unit ID configured in the SUD OpenPaaS console |
| style | Object | Yes | Position and dimensions of the maximum available Banner container |
| 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) |
object.style
| Property | Type | Required | Description |
|---|---|---|---|
| left | number | Yes | Maximum container's top-left X-coordinate, in logical pixels |
| top | number | Yes | Maximum container's top-left Y-coordinate, in logical pixels |
| width | number | Yes | Maximum available width; must be positive |
| height | number | Yes | Maximum 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.
| Property | Type | Description |
|---|---|---|
| realWidth | number | Actual ad width in logical pixels; 0 before the first successful display |
| realHeight | number | Actual 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/heightdirectly inside theonResizelistener. - To query the actual size from other game logic, read
bannerAd.style.realWidth/bannerAd.style.realHeight. Both are0before the first successful display.
Methods
| Method | Return value | Description |
|---|---|---|
show() | Promise<void> | Requests that the ad be shown |
hide() | Promise<void> | Hides the ad |
destroy() | void | Destroys 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
| Method | Description |
|---|---|
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:
| Property | Type | Description |
|---|---|---|
| errCode | number | See ad error codes |
| errMsg | string | Error message |
onResize Callback Parameters
The onResize listener receives the following object:
| Property | Type | Description |
|---|---|---|
| width | number | Actual ad width in logical pixels, matching style.realWidth |
| height | number | Actual 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.
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.
