Skip to content

sud.createBannerAd ​

创建 Banner 广告对象。

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

Banner 自动加载受请求频次限制,触发限制时通过 onError 返回错误码(errCode)和错误信息(errMsg)。

参数 ​

Object object ​

属性类型必填说明
adUnitIdstring是SUD OpenPaaS 控制台配置的广告单元 ID
styleObject是Banner 最大可用容器的位置与尺寸
adIntervalsnumber否广告自动刷新的间隔时间,单位为秒,参数值必须大于等于 30(预留参数,暂未生效)

object.style ​

属性类型必填说明
leftnumber是最大容器左上角横坐标,逻辑像素
topnumber是最大容器左上角纵坐标,逻辑像素
widthnumber是最大可用宽度,必须大于 0
heightnumber是最大可用高度,必须大于 0

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

当 top 为 0 时,Android 和 iOS 会在必要时将 Banner 下移至顶部安全区下沿;建议预留顶部间距,避免广告紧贴顶部展示。

尺寸单位为逻辑像素(Android 为 dp,iOS 为 pt)。容器尺寸与 pixelRatio 可通过 sud.getContainerInfo 查询;直接使用逻辑宽高设置 Banner 区域,无需乘除 pixelRatio。

容器需要容纳实际广告规格。例如,300×250 的广告无法放入 320×100 的容器;所有广告候选均不适配时,可能返回 -22001,参见广告错误码。请核对游戏预留区域与后台广告规格,调整容器或广告位配置;尺寸适配后仍需等待加载成功。

返回值 ​

BannerAd 广告对象。

BannerAd.style 实际尺寸 ​

bannerAd.style.realWidth 和 bannerAd.style.realHeight 是只读的实际展示尺寸,供小游戏 JS 开发者调整广告周围的游戏 UI 或记录尺寸用于排查。

属性类型说明
realWidthnumber实际广告宽度,逻辑像素;首次成功展示前为 0
realHeightnumber实际广告高度,逻辑像素;首次成功展示前为 0

style.width / style.height 表示最大可用区域,style.realWidth / style.realHeight 表示实际广告尺寸。收到 onResize 时可读取对应的实际尺寸,最大可用宽高保持不变。

  • 响应尺寸变化时:在 onResize 监听函数中直接读取回调参数 width / height。
  • 在其他游戏逻辑中查询实际尺寸时:读取 bannerAd.style.realWidth / bannerAd.style.realHeight;首次成功展示前为 0。

方法 ​

方法返回值说明
show()Promise<void>发起广告展示
hide()Promise<void>隐藏广告
destroy()void销毁广告;销毁后不可继续使用

show() 和 hide() 的 Promise 仅表示方法调用结果;加载或展示失败通过 onError 通知。

事件 ​

方法说明
onLoad(listener)监听广告加载成功
offLoad(listener)移除指定的加载成功监听函数
onError(listener)监听广告加载或展示失败
offError(listener)移除指定的错误监听函数
onResize(listener)监听成功展示后的首次实际尺寸及后续尺寸变化
offResize(listener)移除指定的尺寸变化监听函数

onError 回调参数 ​

onError 的监听函数接收以下对象:

属性类型说明
errCodenumber参见广告错误码
errMsgstring错误信息

onResize 回调参数 ​

onResize 的监听函数接收以下对象:

属性类型说明
widthnumber实际广告宽度,逻辑像素,与 style.realWidth 一致
heightnumber实际广告高度,逻辑像素,与 style.realHeight 一致

广告真实展示成功后首次通知实际尺寸,之后仅实际尺寸变化时再次通知;加载成功但未展示、展示失败、同尺寸或仅位置变化不触发通知。show() 的 Promise 成功不等于真实展示成功。仍应在 onLoad 后调用 show(),不要等待 onResize 才展示。

示例代码 ​

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

示例中的高度 100 仅用于演示布局,应根据实际广告规格预留空间;它无法容纳高度为 250 的广告。

javascript
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() 绑定到场景退出时机。完整流程见 游戏开发示例。