sud.createBannerAd

创建 banner 广告组件。每次调用该方法创建 banner 广告都会返回一个全新的实例。创建后自动加载，加载成功通过 BannerAd.onLoad() 通知，加载或展示失败通过 BannerAd.onError() 通知。

createBannerAd(params: {
    adUnitId: string;
    style: {
        left: number;
        top: number;
        width: number;
        height: number;
    };
    /** 广告自动刷新的间隔时间，单位为秒，必须大于等于 30（预留参数，暂未生效） */
    adIntervals?: number;
}): BannerAd;

Banner 自动加载受请求频次限制（现状 10 秒内重复请求会触发），触发限制时通过 BannerAd.onError() 返回错误码（errCode）和错误信息（errMsg）。

参数

Object object

属性	类型	默认值	必填	说明
adUnitId	string		是	SUD OpenPaaS 控制台配置的广告单元 ID
style	Object		是	banner 广告最大可用容器的位置与尺寸
adIntervals	number		否	广告自动刷新的间隔时间，单位为秒，参数值必须大于等于 30（预留参数，暂未生效）

object.style 的结构

属性	类型	默认值	必填	说明
left	number		是	最大容器左上角横坐标，逻辑像素
top	number		是	最大容器左上角纵坐标，逻辑像素
width	number		是	最大可用宽度，必须大于 0
height	number		是	最大可用高度，必须大于 0

width / height 表示最大可用区域，广告在区域内水平居中、顶部对齐，不拉伸、不裁剪；left / top 表示该区域的左上角坐标。

尺寸单位为逻辑像素（Android 为 dp，iOS 为 pt）。容器尺寸与 pixelRatio 可通过 sud.getContainerInfo 查询；直接使用逻辑宽高设置 banner 广告区域，无需乘除 pixelRatio，BannerAd.onResize() 提供的实际宽高同样无需再换算。

返回值

BannerAd

banner 广告组件。

style.width / style.height 表示最大可用区域，style.realWidth / style.realHeight 是只读的实际展示尺寸，首次成功展示前为 0。收到 BannerAd.onResize() 通知时可读取对应的实际尺寸，最大可用宽高保持不变。

示例代码

进入场景时创建 banner 广告，收到 BannerAd.onLoad() 通知后展示。下面以全屏游戏为例，通过 sud.getContainerInfo 在顶部预留与容器等宽、最高 100 逻辑像素的广告区域；游戏 UI 应避开该区域。分屏或嵌入式游戏应按实际布局确定预留区域。

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

// adIntervals 为可选参数，暂未生效
const adIntervals = 30;

const bannerAd = sud.createBannerAd({
    adUnitId: 'adunit-xxxxxxxx',
    style: {
        left: 0,
        top: 0,
        // 直接使用逻辑宽高设置预留区域。
        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 广告失败', err);
    onBannerSceneExit();
}

function onResize({ width, height }) {
    if (disposed) return;
    // 对应 bannerAd.style.realWidth / realHeight，可用于调整周围的游戏 UI。
    console.log('Banner 实际尺寸', 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);

预留区域与容器等宽，广告在区域内水平居中、顶部对齐，因此视觉上即为居中展示。将 onBannerSceneExit() 绑定到场景退出时机；即使广告仍在加载也应调用，销毁后迟到的加载回调不会再调用 show()。