sud.createBannerAd
创建 Banner 广告对象。
createBannerAd(params: {
adUnitId: string;
style: {
left: number;
top: number;
width: number;
height: number;
};
/** 广告自动刷新的间隔时间,单位为秒,必须大于等于 30(预留参数,暂未生效) */
adIntervals?: number;
}): BannerAd;Banner 自动加载受请求频次限制,触发限制时通过 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 表示该区域的左上角坐标。
当 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 或记录尺寸用于排查。
| 属性 | 类型 | 说明 |
|---|---|---|
| realWidth | number | 实际广告宽度,逻辑像素;首次成功展示前为 0 |
| realHeight | number | 实际广告高度,逻辑像素;首次成功展示前为 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 的监听函数接收以下对象:
| 属性 | 类型 | 说明 |
|---|---|---|
| errCode | number | 参见广告错误码 |
| errMsg | string | 错误信息 |
onResize 回调参数
onResize 的监听函数接收以下对象:
| 属性 | 类型 | 说明 |
|---|---|---|
| width | number | 实际广告宽度,逻辑像素,与 style.realWidth 一致 |
| height | number | 实际广告高度,逻辑像素,与 style.realHeight 一致 |
广告真实展示成功后首次通知实际尺寸,之后仅实际尺寸变化时再次通知;加载成功但未展示、展示失败、同尺寸或仅位置变化不触发通知。show() 的 Promise 成功不等于真实展示成功。仍应在 onLoad 后调用 show(),不要等待 onResize 才展示。
示例代码
进入场景时创建 Banner,收到 onLoad 后展示。下面以全屏游戏为例,通过 sud.getContainerInfo 在顶部预留与容器等宽、最高 100 逻辑像素的广告区域;游戏 UI 应避开该区域。分屏或嵌入式游戏应按实际布局确定预留区域,见 布局说明。
示例中的高度 100 仅用于演示布局,应根据实际广告规格预留空间;它无法容纳高度为 250 的广告。
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() 绑定到场景退出时机。完整流程见 游戏开发示例。
