一、广告开发者接入准备
1、小游戏开发者站创建小游戏
2、米盟SSP后台创建广告位
- 登录米盟SSP后台(ssp.xiaomi.com),注意:登录SSP后台的小米账号,需要与上面小游戏开发者站使用的账号一致,否则会无法找到对应小游戏
- 找到对应的小游戏并点击“启用”,注意:不启用应用不可创建广告位
- 在“我的广告位”中点击“新的广告位”开始创建广告位
- 在“所属应用”中选择需要创建广告位的小游戏
- 选择要创建的广告位并点击“保存”
- 保存后点击“启用”,启用广告位后,广告位才可正常下发广告,注意:此处的广告位ID为后续接入中用到的adUnitId
3、米盟SSP后台应用状态说明
当您创建小游戏后,米盟应用列表即会显示该小游戏的信息,应用状态包括:
未启用:该应用未启用流量变现功能,您可点击“立即启用”。
未通过审核:该应用没有通过应用商店的审核或者在审核中,米盟不会向该应用返回真实广告(点击广告不计费),开发者可以点击“应用详情”先创建广告位并接入调试,待审核通过后登陆米盟再开启广告位即可拉取到正式计费的广告。
运行中:该应用已经通过应该商店的审核,可以正常接收米盟广告。
4、广告调试
请参见:https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1757
5、广告结算相关
整体结算流程同APK游戏,详见指引文档中“分成结算”相关内容
二、广告API文档
1、横幅广告
- bannerAd qg.createBannerAd(Object object)
创建横幅广告组件
参数Object object:
属性 | 类型 | 必填 | 说明 |
adUnitId | string | 是 | 横幅广告位ID,获取方式详见上面SSP后台广告位创建 |
style | Object | 是 | 横幅广告组件的样式 |
adIntervals | number | 否 | 广告自动刷新的间隔时间,单位为秒,参数值必须大于等于30(该参数不传入时 Banner 广告不会自动刷新) |
代码示例:
let bannerAd =qg.createBannerAd({
adUnitId: 'xxx',
style:{
left:0,
top: 800,
width:1080
}
})
- style的结构
属性 | 类型 | 是否必填 | 说明 |
left | number | 否 | 横幅 广告组件的左上角横坐标 |
top | number | 否 | 横幅广告组件的左上角纵坐标 |
width | number | 否 | 横幅广告组件的宽度 |
height | number | 否 | 横幅广告组件的高度 |
返回值:bannerAd(横幅广告组件)
- bannerAd.style
横幅广告组件的尺寸会根据开发者设置的宽度,即 style.width 进行等比缩放,缩放的范围是designWidth * 50%到屏幕宽度。开发者在创建 BannerAd 时设置宽高,也可以在创建后设置,
如:
bannerAd.style.width = 1000
当 style.width 小于 designWidth * 50% 时,会取作 designWidth * 50%。
当 style.width 大于屏幕宽度时,会取作屏幕宽度。 在组件内部会以此值为基准,根据 Banner 广告的标准尺寸,进行缩放。
每当缩放发生且缩放后的尺寸不同时,通过 BannerAd.onResize() 注册的回调函数就会执行。回调函数的参数是一个包含 BannerAd 缩放后的宽和高的对象。BannerAd 的 style.realWidth 和style.realHeight 到经过缩放后的宽和高。
bannerAd.onResize(res => {
console.log(res.width, res.height)
console.log(bannerAd.style.realWidth, bannerAd.style.realHeight)
})
横幅广告不设置位置,默认在屏幕底部。
- bannerAd.show()
展示横幅广告,出错的时候回调 onError,分为加载和展示两个阶段,加载成功回调onLoad
- bannerAd.hide()
隐藏横幅广告
- bannerAd.destroy()
销毁横幅广告
- bannerAd.onError(function callback)
监听横幅广告错误事件
代码示例:
bannerAd.onError((err)=>{
console.log(err)
})
err:Object错误参数,其他广告类型相同
参数 | 类型 | 是否必填 | 说明 |
errMsg | string | 是 | 错误信息 |
errCode | number | 是 | 错误码 |
- bannerAd.onLoad(function callback)
监听横幅广告加载事件,callback无返回值
- bannerAd.onClose(function callback)
监听横幅广告关闭事件
- bannerAd.onResize(function callback)
监听横幅广告尺寸变化事件
Banner广告尺寸会根据开发者设置的宽度进行等比缩放,缩放的范围是 300 到 屏幕宽度,
事件的返回参数中包含真实的宽、高,若宽高不符合需求,可以动态的通过style.width设置改变广告的大小。
注意:如果在 onResize 的回调函数中重设 width 且总是与上一次缩放后的 width 不同,那么可能会导致 onResize 的回调函数一直触发,卡死在 onResize 的回调函数中。
参数:function callback(横幅广告尺寸变化事件的回调函数)
回调参数 Object res:
属性 | 类型 | 说明 |
width | number | 缩放后的宽度 |
height | number | 缩放后的高度 |
- bannerAd.offResize(function callback)
取消监听banner广告尺寸变化事件,callback同onResize的callback一致
- bannerAd.onClick(function callback)
1300+
监听横幅广告点击事件
- bannerAd.offClick(function callback)
1300+
移除横幅广告点击回调
2、插屏广告
interstitialAd qg.createInterstitialAd(Object object)
创建插屏广告组件,同一个 adUnitId,如果已经创建,并且未 destroy,会复用之前的对象,创建后会加载广告素材,素材创建后会自动拉取
参数 Object object:
属性 | 类型 | 必填 | 说明 |
adUnitId | string | 是 | 插屏广告位ID,获取方式详见上面SSP后台广告位创建 |
代码示例:
let interstitialAd =qg.createInterstitialAd({
adUnitId: 'xxx'
})
返回值:interstitialAd插屏广告组件
- interstitialAd.show()
展示插屏广告,插屏广告组件默认是隐藏的,调用 show 方法展示广告
- interstitialAd.destroy()
销毁插屏广告组件
- interstitialAd.onLoad(function callback)
监听视频广告加载事件,callback无返回值
代码示例:
interstitialAd.onLoad(()=> {
console.log("插屏广告加载成功");
interstitialAd.show();
})
- interstitialAd.onClose(function callback)
监听插屏广告关闭事件,callback无返回值
- interstitialAd.onError(function callback)
监听插屏广告错误事件
代码示例:
interstitialAd.onError((err)=> {
console.log(err);
})
- callback回调函数的参数 Object res
属性 | 类型 | 说明 |
errMsg | String | 错误信息 |
errCode | Number | 错误码 |
- interstitialAd.onClick(function callback)
1300+
监听插屏广告点击事件
- interstitialAd.offClick(function callback)
1300+
移除插屏广告点击回调
3、激励视频广告
激励视频广告组件是由客户端原生的图片、文本、视频控件组成的,层级最高,会覆盖在普通组件上,该方法返回的是一个单例,该实例仅对当前页面有效,不允许跨页面使用。
- rewardedVideoAd qg.createRewardedVideoAd(Object object)
参数Object object:
属性 | 类型 | 必填 | 说明 |
adUnitId | string | 是 | 激励视频广告位id,获取方式详见上面SSP后台广告位创建 |
multiton | boolean | 否 | 是否启用多例模式,默认为false |
代码示例:
let rewardedVideoAd = ad.createRewardedVideoAd({
adUnitId: 'xxx'
})
返回值:rewardedVideoAd(激励视频广告组件)
- rewardedVideoAd.load()
加载激励视频广告
- rewardedVideoAd.show()
展示激励视频广告,激励视频广告将从屏幕下方推入(请勿在onLoad回调中调用show())
- rewardedVideoAd.onLoad(function callback)
监听激励视频广告加载事件,callback无返回值
- rewardedVideoAd.onClose(function callback)
监听用户点击“关闭按钮”按钮的事件
参数:function callback
参数 | 类型 | 说明 |
isEnded | boolean | 视频是否是在用户完整观看的情况下被关闭的 |
- rewardedVideoAd.onError(function callback)
监听激励视频错误事件
参数:function callback(激励视频错误事件的回调函数)
- callback回调函数的参数 Object res
属性 | 类型 | 说明 |
errMsg | String | 错误信息 |
errCode | Number | 错误码 |
- rewardedVideoAd.onClick(function callback)
1300+
监听激励视频广告点击事件
- rewardedVideoAd.offClick(function callback)
1300+
移除激励视频广告点击回调
4、原生模板(最小支持引擎版本1110+)
versionCode >= 11100001
- customAd qg.createCustomAd(Object object)
创建模板广告组件
参数Object object:
属性 | 类型 | 是否必填 | 说明 |
adUnitId | string | 是 | 模板广告位ID,获取方式详见上面SSP后台广告位创建 |
style | Object | 是 | 模板广告组件的样式 |
代码示例:
let customAd =qg.createCustomAd({
adUnitId: 'xxx',
style:{
left:0,
top: 800,
width:1080
}
})
- style的结构:
属性 | 类型 | 是否必填 | 说明 |
left | number | 否 | 模板广告组件的左上角横坐标 |
top | number | 否 | 模板广告组件的左上角纵坐标 |
width | number | 否 | 模板广告组件的宽度 |
height | number | 否 | 模板广告组件的高度 |
返回值:CustomAd(模板广告组件)
- customAd.style
模板广告组件的尺寸会根据开发者设置的宽度和高度进行展示。开发者在创建 CustomAd时设置宽高,也可以在创建后设置,
如:
customAd.style.width = 1000
当 style.width 大于屏幕宽度时,会取作屏幕宽度。
模板广告不设置位置,默认在屏幕底部。
- customAd.show()
展示模板广告,出错的时候回调 onError,分为加载和展示两个阶段,加载成功回调onLoad
- customAd.hide()
模板横幅广告
- customAd.destroy()
销毁模板广告
- customAd.onShow(function callback) | offShow 解除监听
监听模板广告展示事件
- customAd.onError(function callback) | offError 解除监听
监听模板广告错误事件
代码示例:
customAd.onError((err)=>{
console.log(err)
})
err:Object错误参数,其他广告类型相同
参数 | 类型 | 是否必填 | 说明 |
errMsg | string | 是 | 错误信息 |
errCode | number | 是 | 错误码 |
- customAd.onLoad(function callback) | offLoad 解除监听
监听模板广告加载事件,callback无返回值
- customAd.onClose(function callback) | offClose解除监听
监听模板广告关闭事件
- customAd.onClick(Function callback) | offClick 解除监听
1300+
监听模版广告点击事件
5、开屏广告
直接启用系统开屏即可
6、互推盒子广告
7、常见错误码
错误码是通过onError获取到的错误信息,errCode返回值如下表:
错误码 | 问题描述 | 原因 | 解决方案 |
1000 | 后端接口调用失败 | 通常为网络异常 | 请更换网络重试 |
1001 | 参数错误 | 使用方法错误 | 请仔细检查接入代码与文档是否一致 |
1002 | 广告单元无效 | 可能是拼写错误、或者误用了其他 APP 的广告 ID | 请前往米盟 ssp.xiaomi.com 确认广告位 ID |
1003 | 内部错误 | 该项错误不是开发者的异常情况 | 一般情况下忽略一段时间即可恢复 |
1004 | 无合适的广告 | - | 属于正常情况,且开发者需要针对这种情况做形态上的兼容 |
1005 | 广告组件审核中 | 你的广告正在被审核,无法展现广告 | 请前往米盟 ssp.xiaomi.com 确认审核状态,且开发者需要针对这种情况做形态上的兼容 |
1007 | 广告组件被驳回 | 你的广告能力已经被封禁,封禁期间无法展现广告 | 请前往米盟 ssp.xiaomi.com 确认封禁状态 |
1008 | 广告单元已关闭 | 该广告位的广告能力已经被关闭 | 请前往米盟 ssp.xiaomi.com 启用对应广告位 |
1107 | 禁止后台渲染广告 | 防止游戏后台状态非法渲染广告 | 在前台状态再展示广告 |
4001007 | 快应用框架版本低 | 快应用框架版本低于1.9.0.6 | 检查快应用框架版本是不是1.9.0.6及以上,查看路径:设置-应用设置-系统应用设置-快应用服务框架,如不是请到应用商店进行更新,我的-应用升级-查看全部升级 |
300061 | 广告位"接入方式"错误 | 该广告位ID"接入方式"为非API类型 | 请在米盟后台重新创建广告位,广告位ID的"接入方式"为API时,可正常使用 |
错误码 | 说明 | 排查建议 |
0 | 广告请求成功,有广告填充 | |
1 | 广告请求成功,无广告填充 | |
100401 | 联盟投放限制过滤 | 调整米盟开发者后台的投放限制策略,如屏蔽关键词、包名等投放限制 |
300001 | 广告位不存在 | 确认米盟开发者后台上广告位的状态,检查广告位id是否与后台保持一致 |
300002 | 广告位在米盟SSP被暂停 | 确认米盟开发者后台上广告位的状态 |
300003 | upId不存在 | 检查广告位id是否与后台保持一致 |
300004 | 广告位被加入黑名单 | 广告位处于封禁状态,请及时查看米盟开发者后台提醒 |
300005 | 应用在米盟SSP被暂停 | 检查应用下广告位全部被暂停 |
300006 | 应用被加入黑名单 | 广告位处于封禁状态,请及时查看米盟开发者后台提醒 |
300007 | 应用不存在 | 确认广告位的应用信息是否正确 |
300009 | 应用未上架 | 确认米盟开发者后台应用状态 |
300061 | 请求api不支持当前广告位 | 确认请求api和广告位的接入方式是否匹配 |
300201 | 缺少 clientInfo | 确认广告请求的clientInfo信息 |
300202 | clientInfo 不是合法的 json 格式 | 确认请求中clientInfo的格式是否与接入文档保持一致 |
300203 | 没有上报 os 信息,或者 os 信息不正确 | 确认请求中deviceInfo的os信息 |
300204 | 没有上报ip信息 | 确认广告请求的ip信息 |
300205 | 没有上报connectionType | 确认广告请求中是否缺失connectionType |
300206 | 请求信息校验 | 校验是否填上必要的请求信息 |
300207 | 没有上报packageName | 确认广告请求的packageName是否正常上报 |
300208 | 缺少deviceInfo | 确认deviceInfo是否为空 |
300209 | 没有上报userInfo | 确认广告请求的uerInfo是否正常上报 |
300210 | 没有上报appInfo | 确认广告请求的appInfo是否正常上报 |
300211 | 缺少impRequest | 确认 广告请求的cilentInfo中的impRequest是否存在 |
300212 | 没有上报 make 信息 | 确认 广告请求的deviceInfo中的make信息是否正确上报 |
300215 | 频控限制 | 请求频率过高。避免同一设备在一段时间内高频拉取广告,如在开发测试阶段,可尝试更换测试设备解决 |
300216 | 设备限制 | 如在开发测试阶段,可尝试更换测试设备解决,如无法自行解决,可联系米盟进行解决 |
300219 | SSP平台上应用的包名与广告请求中的包名不一致 | 实际发出广告请求的包名和在米盟开发者后台上应用的包名不匹配,需要检查发出广告的应用的包名,建议去开发者后台确认包名与使用的包名是否一致 |
300221 | 设备黑名单 | 联系米盟进行排查 |
300238 | 联盟投放限制过滤 | 调整广告的投放限制策略 |
300249 | 缺少 ua 字段 | 检查请求中的ua字段是否正确上报 |
300251 | 缺少 model 字段 | 检查请求中的model字段是否正确上报 |
300252 | 目标价过滤 | 请适当调整CPM目标价 |
300407 | 低转化率广告位限流 | 广告位后端转化效果差,因此填充率被限制。需根据广告位的广告数据分析流量转化效率差的具体原因,建议关注转化率、用户留存等数据,提高广告位转化效率。 |
301003 | 无合适预算 | 联系米盟进行解决 |
301005 | 自渲染广告样式,返回的广告类型不符合用户需要的广告类型,比如用户在SSP后台勾选需要图片,返回的是视频 | 在米盟开发者后台勾选图片+视频元素,最大化广告位填充 |
300254 | 非小米设备 | 检查设备是否为小米手机 |
300411 | 异常设备过滤 | 设备存在异常,请自查流量来源。如在开发测试阶段,可尝试更换测试设备解决 |
300417 | 快框架低版本过滤 | 升级快框架版本 |
300504 | 快应用框架版本>=11030301的用户停止下发原生广告1.0 | 请接入原生广告2.0 |
1000 | 后端错误,调用失败 | |
1001 | 参数错误 | |
1002 | 广告单元无效 | |
1003 | 内部错误 | |
1004 | 无合适的广告 | |
1005 | 广告组件审核中 | |
1006 | 广告组件被驳回 | |
1007 | 广告能力被封禁 | |
1008 | 广告位的广告能力已关闭 | |
1009 | 广告加载超时 | |
1100 | 过于频繁调用相关的API | |
1101 | 广告在加载后,⻓时间没有展示,广告信息已过期 | |
1102 | 调用了不支持的方法 | |
1103 | 环境监测失败,如应用无权限等 | |
1104 | 网络错误 | |
1105 | 广告未加载成功 | |
1106 | 广告展示失败 | |
1107 | 后台无法调用广告能力 | 展示广告时当前快应用页面必须在前台且用户可见 |
2000 | 未知错误 |
更多错误码详见:https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1472
三、广告变现指南
https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1459
四、广告接入规范
互推盒子广告规范:https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1119
其他广告规范:https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1460