搜索
推广与变现
游戏联运
广告联盟
应用联运
推广与变现/广告联盟/操作指南/广告接入/小游戏广告SDK接入文档
小游戏广告SDK接入文档更新时间: 2024-10-10 17:36:00

一、广告开发者接入准备

1、小游戏开发者站创建小游戏

2、米盟SSP后台创建广告位

  • 登录米盟SSP后台(ssp.xiaomi.com),注意:登录SSP后台的小米账号,需要与上面小游戏开发者站使用的账号一致,否则会无法找到对应小游戏
  • 找到对应的小游戏并点击“启用”,注意:不启用应用不可创建广告位

  • 在“我的广告位”中点击“新的广告位”开始创建广告位

  • 在“所属应用”中选择需要创建广告位的小游戏

  • 选择要创建的广告位并点击“保存”

  • 保存后点击“启用”,启用广告位后,广告位才可正常下发广告,注意:此处的广告位ID为后续接入中用到的adUnitId

3、米盟SSP后台应用状态说明

当您创建小游戏后,米盟应用列表即会显示该小游戏的信息,应用状态包括:
未启用:该应用未启用流量变现功能,您可点击“立即启用”。
未通过审核:该应用没有通过应用商店的审核或者在审核中,米盟不会向该应用返回真实广告(点击广告不计费),开发者可以点击“应用详情”先创建广告位并接入调试,待审核通过后登陆米盟再开启广告位即可拉取到正式计费的广告。
运行中:该应用已经通过应该商店的审核,可以正常接收米盟广告。

4、广告调试

接好API的小游戏可以用快应用调试器进行调试,米盟提供如下测试广告位ID,帮助开发者在开发过程中调试广告,提审前请务必将广告位ID更换成正式ID,否则会影响审核结果,测试用APPID:2882303761517525824

广告位广告位 ID广告类型
激励视频77295ab0558fa54fc5cc9ed6a28b6da7竖版激励视频
1cde071f6fddc0b64ec4c45f55c888ab横版激励视频
插屏f54f3dfc0ba63cf3dbf582816ee069d7竖版插屏
2e3d390df5f0b1143766041161e61b16横版插屏
横幅81e6cbe35e56b53eebbc547fd1bc5614横幅(不区分横竖)
原生-自渲染da11b7e8c582ee7d1acf16a627ea6b34原生大图
3a4425134fa94da68595d9d31a2b4ed0原生小图
1d00f0ba118b2e895d81b05e4906b9c6原生组图
开屏无需测试,后台开启广告位上线后即可下发竖版开屏

5、广告结算相关

整体结算流程同APK游戏,详见指引文档中“分成结算”相关内容

二、广告API文档

1、横幅广告

  • bannerAd qg.createBannerAd(Object object)

创建横幅广告组件

参数Object object:

属性类型必填说明
adUnitIdstring横幅广告位ID,获取方式详见上面SSP后台广告位创建
styleObject横幅广告组件的样式
adIntervalsnumber广告自动刷新的间隔时间,单位为秒,参数值必须大于等于30(该参数不传入时 Banner 广告不会自动刷新)

代码示例:

let bannerAd =qg.createBannerAd({

adUnitId: 'xxx',

style:{

left:0,

top: 800,

width:1080

}

})
  • style的结构
属性类型是否必填说明
leftnumber横幅 广告组件的左上角横坐标
topnumber横幅广告组件的左上角纵坐标
widthnumber横幅广告组件的宽度
heightnumber横幅广告组件的高度

返回值: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错误参数,其他广告类型相同

参数类型是否必填说明
errMsgstring错误信息
errCodenumber错误码
  • 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:

属性类型说明
widthnumber缩放后的宽度
heightnumber缩放后的高度
  • 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:

属性类型必填说明
adUnitIdstring插屏广告位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
属性类型说明
errMsgString错误信息
errCodeNumber错误码
  • interstitialAd.onClick(function callback) 1300+

监听插屏广告点击事件

  • interstitialAd.offClick(function callback) 1300+

移除插屏广告点击回调

3、激励视频广告

激励视频广告组件是由客户端原生的图片、文本、视频控件组成的,层级最高,会覆盖在普通组件上,该方法返回的是一个单例,该实例仅对当前页面有效,不允许跨页面使用。

  • rewardedVideoAd qg.createRewardedVideoAd(Object object)

参数Object object:

属性类型必填说明
adUnitIdstring激励视频广告位id,获取方式详见上面SSP后台广告位创建
multitonboolean是否启用多例模式,默认为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

参数类型说明
isEndedboolean视频是否是在用户完整观看的情况下被关闭的
  • rewardedVideoAd.onError(function callback)

监听激励视频错误事件

参数:function callback(激励视频错误事件的回调函数)

  • callback回调函数的参数 Object res
属性类型说明
errMsgString错误信息
errCodeNumber错误码
  • rewardedVideoAd.onClick(function callback) 1300+

监听激励视频广告点击事件

  • rewardedVideoAd.offClick(function callback) 1300+

移除激励视频广告点击回调

4、原生模板(最小支持引擎版本1110+)

versionCode >= 11100001

  • customAd qg.createCustomAd(Object object)

创建模板广告组件
参数Object object:

属性类型是否必填说明
adUnitIdstring模板广告位ID,获取方式详见上面SSP后台广告位创建
styleObject模板广告组件的样式

代码示例:

let customAd =qg.createCustomAd({
adUnitId: 'xxx',
style:{
left:0,
top: 800,
width:1080
}
})

  • style的结构:
属性类型是否必填说明
leftnumber模板广告组件的左上角横坐标
topnumber模板广告组件的左上角纵坐标
widthnumber模板广告组件的宽度
heightnumber模板广告组件的高度

返回值: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错误参数,其他广告类型相同

参数类型是否必填说明
errMsgstring错误信息
errCodenumber错误码

  • 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被暂停确认米盟开发者后台上广告位的状态
300003upId不存在检查广告位id是否与后台保持一致
300004广告位被加入黑名单广告位处于封禁状态,请及时查看米盟开发者后台提醒
300005应用在米盟SSP被暂停检查应用下广告位全部被暂停
300006应用被加入黑名单广告位处于封禁状态,请及时查看米盟开发者后台提醒
300007应用不存在确认广告位的应用信息是否正确
300009应用未上架确认米盟开发者后台应用状态
300061请求api不支持当前广告位确认请求api和广告位的接入方式是否匹配
300201缺少 clientInfo确认广告请求的clientInfo信息
300202clientInfo 不是合法的 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设备限制如在开发测试阶段,可尝试更换测试设备解决,如无法自行解决,可联系米盟进行解决
300219SSP平台上应用的包名与广告请求中的包名不一致实际发出广告请求的包名和在米盟开发者后台上应用的包名不匹配,需要检查发出广告的应用的包名,建议去开发者后台确认包名与使用的包名是否一致
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

上一篇:
下一篇: