vConsole

在真机上,如果想要查看 console API 输出的日志内容和额外的调试信息,需要在点击屏幕右上角的按钮打开的菜单里选择「打开调试」。此时微信小程序/小游戏会退出,重新打开后右下角会出现一个 vConsole 按钮。点击 vConsole 按钮可以打开日志面板。

微信小程序和小游戏的 vConsole 展示内容会有一定差别,下图左边是微信小程序 vConsole,右边是小游戏 vConsole

vConsole 使用说明

由于实现机制的限制,开发者调用 console API 打印的日志内容,是转换成 JSON 字符串后传输给 vConsole 的,导致 vConsole 中展示的内容会有一些限制:

  • 除了 NumberStringBooleannull 外,其他类型都会被作为 Object 处理展示,打印对象及原型链中的 Enumerable 属性。
  • InfinityNaN 会显示为 null
  • undefinedArrayBufferFunction 类型无法显示
  • 无法打印存在循环引用的对象
let a = {}
a.b = a
console.log(a) // 2.3.2 以下版本,会打印 `An object width circular reference can't be logged`

针对上述问题,微信小程序/小游戏在使用 vConsole 时做了一些处理

  • 2.3.2 及以上版本,支持打印循环引用对象。循环引用的对象属性会显示引用路径,@表示对象本身。
const circular = { x: {}, c: {} }
circular.x = [{ promise: Promise.resolve() }]
circular.a = circular
circular.c.x0 = circular.x[0]

console.log(circular)
// "{a: '<Circular: @>', c: {x0: '<Circular: @.x[0]>'}, x: [{promise: '<Promise>'}]}"
  • 2.3.1 及以上版本,支持展示所有类型的数据。基础库会对日志内容进行一次转换,经过转换的内容会使用<>包裹。如:

    • <Function: func>
    • <Undefined>
    • <Infinity>
    • <Map: size=0>
    • <ArrayBuffer: byteLength=10>
  • 2.2.3 ~ 2.3.0 版本中,可以展示 ArrayBufferFunction 类型,undefined 会被打印为字符串 'undefined'

注:尽量避免在非调试情景下打印结构过于复杂或内容过长的日志内容(如游戏引擎中的精灵或材质对象等),可能会带来额外耗时。为了防止异常发生,日志内容超过一定长度会被替换为<LOG_EXCEED_MAX_LENGTH>,此时需要开发者裁剪日志内容。

调试

开发者可以借助下列工具进行微信小程序的调试。

  • vConsole:在手机上查看console API 输出的日志内容和额外的调试信息。
  • Source Map:还原 JS 错误堆栈
  • 真机调试: 利用开发者工具,通过网络连接,对手机上运行的微信小程序进行调试,帮助开发者更好的定位和查找在手机上出现的问题。
  • 实时日志:快捷地排查微信小程序漏洞、定位问题

四、获取微信小程序结算收入数据及结算主体信息(publisher_settlement)

需要向相应接口调用地址增加以下GET请求参数:

参数 是否必须 说明
page 数据返回页数
page_size 每页返回数据条数
start_date 获取数据的开始时间 yyyy-mm-dd
end_date 获取数据的结束时间 yyyy-mm-dd

请注意: 只要与获取数据的起止时间有重合,结算区间对应的数据都将返回。例如,请求2月11日至3月26日的数据,将会返回2月上半月、2月下半月、3月上半月、3月下半月四个结算区间的数据。


返回参数说明(publisher_settlement)

参数 说明
err_msg 返回错误信息
ret 错误码
body 主体名称
revenue_all 累计收入
penalty_all 扣除金额
settled_revenue_all 已结算金额
settlement_list: date 数据更新时间
settlement_list: zone 日期区间
settlement_list: month 收入月份
settlement_list: order 1 = 上半月,2 = 下半月
settlement_list: sett_status 1 = 结算中;2、3 = 已结算;4 = 付款中;5 = 已付款
settlement_list: settled_revenue 区间内结算收入
settlement_list: sett_no 结算单编号
settlement_list: mail_send_cnt 申请补发结算单次数
settlement_list: slot_revenue: slot_id 产生收入的广告位
settlement_list: slot_revenue: slot_settled_revenue 该广告位结算金额
total_num 请求返回总条数


返回数据包示例(publisher_settlement)

{
    "base_resp":{
        "err_msg":"ok",
        "ret":0
    },
    "body":"深圳市腾讯计算机系统有限公司",
    "penalty_all":0,
    "revenue_all":5178368698,
    "settled_revenue_all":2613696765,
    "settlement_list":[
        {
            "date":"2020-03-25",
            "zone":"2020年3月1日至15日"
            "month":"202003",
            "order":1,
            "sett_status":1,
            "settled_revenue":718926045,
            "sett_no":"XXX",
            "mail_send_cnt":"0",
            "slot_revenue":[
                {
                    "slot_id":"SLOT_ID_WEAPP_BANNER",
                    "slot_settled_revenue":34139443
                },
                {
                    "slot_id":"SLOT_ID_WEAPP_REWARD_VIDEO",
                    "slot_settled_revenue":684786602
                }
            ]
        }
    ],
    "total_num":1
}


三、获取微信小程序广告位清单(get_adunit_list)

需要向相应接口调用地址增加以下GET请求参数:

参数 是否必须 说明
page 返回第几页数据
page_size 当页返回数据条数
ad_slot 广告位类型名称
ad_unit_id 广告位id

请注意: 当需要获取全部广告位的清单时,无需传递广告位类型名称及广告位id;当需要获取某类型广告位的清单时,仅需传递广告位类型名称;当需要获取某广告位id的数据时,仅需传递广告位id。


返回参数说明(get_adunit_list)

参数 说明
err_msg 返回错误信息
ret 错误码
ad_slot 广告位类型名称
ad_unit_id 广告位ID
ad_unit_name 广告位名称
ad_unit_size 广告位尺寸
ad_unit_status 广告位状态


返回数据包示例(get_adunit_list)

{
    "base_resp":{
        "err_msg":"ok",
        "ret":0
    },
    "ad_unit":[
        {
            "ad_slot":"SLOT_ID_WEAPP_REWARD_VIDEO",
            "ad_unit_id":"adunit-e9418ee19XXXXX",
            "ad_unit_name":"rewaXXXX",
            "ad_unit_size":[
                {
                    "height":166,
                    "width":582
                }
            ],
            "ad_unit_status":"AD_UNIT_STATUS_ON",
            "ad_unit_type":"AD_UNIT_TYPE_REWARED_VIDEO",
            "appid":"wx0afc78670fXXXX",
            "video_duration_max":30,
            "video_duration_min":6
        }
    ],
    "total_num":1
}


二、获取微信小程序广告细分数据(publisher_adunit_general)

需要向相应接口调用地址增加以下GET请求参数:

参数 是否必须 说明
page 返回第几页数据
page_size 当页返回数据条数
start_date 获取数据的起始日期 yyyy-mm-dd
end_date 获取数据的结束时间 yyyy-mm-dd
ad_slot 广告位类型名称
ad_unit_id 广告位id

请注意: 当需要获取全部广告位的细分数据时,无需传递广告位类型名称及广告位id;当需要获取某类型广告位的细分数据时,仅需传递广告位类型名称;当需要获取某广告位id的细分数据时,仅需传递广告位id。


返回参数说明(publisher_adunit_general)

参数 说明
err_msg 返回错误信息
ret 错误码
list: ad_unit_id 广告位id
list: ad_unit_name 广告位名称
list: stat_item: ad_slot 广告位类型名称
list: stat_item :date 数据日期
list: stat_item :req_succ_count 拉取量
list: stat_item :exposure_count 曝光量
list: stat_item: exposure_rate 曝光率
list: stat_item :click_count 点击量
list: stat_item :click_rate 点击率
list: stat_item :income 收入
list: stat_item :ecpm 广告千次曝光收益(分)
total_num 请求返回总数


返回数据包示例(publisher_adunit_general)

{
    "base_resp":{
        "err_msg":"ok",
        "ret":0
    },
    "list":[
        {
            "ad_unit_id":"adunit-9cedd8514XXXX",
            "ad_unit_name":"激励视频长广告",
            "stat_item":{
                "ad_slot":"SLOT_ID_WEAPP_REWARD_VIDEO",
                "date":"2020-04-10",
                "req_succ_count":138250,
                "exposure_count":74771,
                "exposure_rate":0.54083906,
                "click_count":2242,
                "click_rate":0.029984887,
                "income":93883,
                "ecpm":6.790813743
            }
        }
    ],
    "total_num":1
}


一、获取微信小程序广告汇总数据(publisher_adpos_general)

需要向相应接口调用地址增加以下GET请求参数:

参数 是否必须 说明
page 返回第几页数据
page_size 当页返回数据条数
start_date 获取数据的开始时间 yyyy-mm-dd
end_date 获取数据的结束时间 yyyy-mm-dd
ad_slot 广告位类型名称

请注意: 如果不传递广告位类型名称,将默认返回全部类型广告位的数据。


返回参数说明(publisher_adpos_general)

参数 说明
err_msg 返回错误信息
ret 错误码
list: slot_id 广告位类型id
list: ad_slot 广告位类型名称
list: date 日期
list: req_succ_count 拉取量
list: exposure_count 曝光量
list: exposure_rate 曝光率
list: click_count 点击量
list: click_rate 点击率
list: income 收入(分)
list: ecpm 广告千次曝光收益(分)
summary: req_succ_count 总拉取量
summary: exposure_count 总曝光量
summary: exposure_rate 总曝光率
summary: click_count 总点击量
summary: click_rate 总点击率
summary: income 总收入(分)
summary: ecpm 广告千次曝光收益(分)
total_num list返回总条数


返回数据包示例(publisher_adpos_general)

{
    "base_resp":{
        "err_msg":"ok",
        "ret":0
    },
    "list":[
        {
            "slot_id":3030046789020061,
            "ad_slot":"SLOT_ID_WEAPP_INTERSTITIAL",
            "date":"2020-04-13",
            "req_succ_count":443610,
            "exposure_count":181814,
            "exposure_rate":0.409850995,
            "click_count":10095,
            "click_rate":0.055523777,
            "income":52175,
            "ecpm":286.969100289
        }
    ],
    "summary":{
        "req_succ_count":4406394,
        "exposure_count":1797225,
        "exposure_rate":0.407867522,
        "click_count":100167,
        "click_rate":0.055734257,
        "income":578003,
        "ecpm":321.608591022
    },
    "total_num":1
}


广告预加载接口

基础库 2.14.1 开始支持,低版本需做兼容处理

在微信小程序环境下,支持通过调用wx.preloadAd接口,提前加载广告数据,再后续创建对应广告标签ad,ad-custom时,会自动使用预加载的广告数据,省去创建广告标签时再次拉取广告的耗时。

预加载示例

  wx.preloadAd([{
      unitId: 'adunit-XXX', // 原生模板广告广告单元
      type: 'custom' // 原生模板广告
    },
    {
      unitId: 'adunit-XXX', // banner广告广告单元
      type: 'banner' // banner广告
    },
    {
      unitId: 'adunit-XXX', // 前贴广告广告单元
      type: 'videoPatch' // 视频前贴广告
    },
    {
      unitId: 'adunit-XXX', // 视频广告广告单元
      type: 'video' // 视频广告
    }
  ])

wx.preloadAd(Array object)

object 参数

属性 类型 默认值 必填 说明
unitId string 广告单元id,可在微信小程序管理后台的流量主模块新建
type string 广告单元所属广告位类型
custom 原生模板广告
banner banner广告
videoPatch 视频前贴广告
video 视频广告

注意事项

1、预加载是否成功对开发者无感知,广告使用方式同无预加载一致即可。

2、广告单元id和广告单元所属广告位类型需要匹配成功,否则会导致无法正常使用预加载数据。

3、在合适的场景使用预加载接口(如pageA调用预加载,pageB调用广告展示,pageA跳转pageB),留充足的时间间隔给到接口调用和广告标签创建才能体现预加载的优势。

4、如果在进入首页就有需要展示广告,且后续广告无新增,刷新等逻辑,无需调用预加载。

5、如果在进入首页就有需要展示广告,后续有新增,刷新逻辑,可在app.js中调用预加载接口。

6、广告单元预加载后,会带来MP后台广告数据的拉取量增长,可能出现曝光率下降现象。建议开发者关注曝光量绝对值变化规律。

原生模板广告

微信小程序广告流量主操作指引:文档地址
开发者可以使用 ad-custom 组件创建 原生模板 广告组件,原生模板 广告组件在创建后会自动拉取广告数据并显示。

广告尺寸设置

原生模板 广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度调整广告的尺寸。 广告外层组件的宽度和具体模板相关,具体可以参考模板编辑器文档。

/* 外层组件的宽度可设置成100%或具体数值 */
.adContainer {
  width: 100%;
}
<view class="adContainer">
  <ad-custom unit-id="xxxx"></ad-custom>
</view>

广告事件监听

原生模板 广告在创建后会自动拉取广告。开发者可以通过 ad-custom 组件的 onloadonerror 事件监听广告拉取成功或失败,同时可通过onclose事件监听广告关闭。

<view class="adContainer">
  <ad-custom unit-id="xxxx" bindload="adLoad" binderror="adError" bindclose="adClose"></ad-custom>
</view>
Page({
  adLoad() {
    console.log('原生模板广告加载成功')
  },
  adError(err) {
    console.log('原生模板广告加载失败', err)
  },
  adClose() {
    console.log('原生模板广告关闭')
  },
})

广告定时刷新

开发者可以在创建 原生模板 广告时传入 ad-intervals 参数实现广告的定时刷新,ad-intervals 参数为数字类型,单位为秒。注意:自动刷新的间隔不能低于30秒,因此 ad-intervals 的参数值必须大于或等于30。

<view class="adContainer">
  <ad-custom unit-id="xxxx" ad-intervals="30"></ad-custom>
</view>

监听广告隐藏

  • 矩阵格子广告触发型特殊说明: 用户在点击右上角关闭按钮时,广告将通过控制 元素的样式 display: none 使其隐藏。 开发者可通过 ad-custom 组件的 onhide 事件监听隐藏事件,在必要时机通过改些 display 样式使广告重新展示。
<ad-custom unit-id="xxxx" bindhide="adHide"></ad-custom>

Grid 广告

微信小程序广告流量主操作指引:文档地址
开发者可以使用 ad 组件创建 Grid 广告组件,Grid 广告组件在创建后会自动拉取广告数据并显示。

广告尺寸设置

Grid 广告不允许直接设置样式属性,默认宽度为100%(width: 100%),高度会自动等比例计算,因此开发者可以设置广告外层组件的宽度来调整广告的尺寸。格子广告有最小尺寸限制,5个格子的形态最小宽度为331px,8个格子的形态最小宽度为294px。

/* 外层组件的宽度可设置成100%或具体数值 */
.adContainer {
  width: 100%;
}
<view class="adContainer">
  <ad unit-id="xxxx" ad-type="grid" ad-theme="white" grid-count="5"></ad>
</view>

广告事件监听

Grid 广告在创建后会自动拉取广告。开发者可以通过 ad 组件的 onloadonerror 事件监听广告拉取成功或失败,可以通过 onclose 事件监听广告被关闭。

<view class="adContainer">
  <ad unit-id="xxxx" ad-type="grid" ad-theme="white" grid-count="5" bindload="adLoad" binderror="adError" bindclose="adClose"></ad>
</view>
Page({
  adLoad() {
    console.log('Grid 广告加载成功')
  },
  adError(err) {
    console.log('Grid 广告加载失败', err)
  },
  adClose() {
    console.log('Grid 广告关闭')
  }
})

广告主题样式设置

微信小程序视频广告组件提供黑、白两种主题样式,开发者可以在创建视频广告时传入ad-theme参数实现主题样式选择,ad-theme参数为字符串类型,参数值可选whiteblack

<view class="adContainer">
  <ad unit-id="xxxx" ad-type="grid" ad-theme="white"></ad>
</view>
<view class="adContainer">
  <ad unit-id="xxxx" ad-type="grid" ad-theme="black"></ad>
</view>

广告格子个数设置

微信小程序视频广告组件提供黑、白两种主题样式,开发者可以在创建视频广告时传入grid-count参数实现格子个数选择,grid-count参数为数字类型,参数值可选58

<view class="adContainer">
  <ad unit-id="xxxx" ad-type="grid" grid-count="5"></ad>
</view>
<view class="adContainer">
  <ad unit-id="xxxx" ad-type="grid" grid-count="8"></ad>
</view>

视频前贴广告

微信小程序广告流量主操作指引:文档地址
开发者可以在 video 组件中添加属性配置,创建微信小程序视频前贴广告组件,视频广告组件在创建后会自动拉取广告数据,视频播放前展示广告。

广告样式

展示样式在开发者所设置的video组件中,以16:9的比例,垂直或者水平居中

广告创建

在video 组件中添加了以下广告相关的属性配置,设置ad-unit-id后可以展示对应广告

属性 类型 默认值 必填 说明
ad-unit-id string 广告单元id,可在微信小程序管理后台的流量主模块新建
bindadload eventhandle 广告加载成功的回调
bindaderror eventhandle 广告加载失败的回调,返回码同ad组件
bindadclose eventhandle 广告关闭的回调
bindadplay eventhandle 广告开始,结束播放的回调 event.detail = {type: ‘begin/end’}

添加广告单元,绑定广告事件

<video 
  class="xxx"
  src="xxx"
  bindadplay="onAdplay"
  bindadload="onAdload"
  bindadclose="onAdclose"
  bindaderror="onAdError"
  ad-unit-id="xxx"
>
</video>

监听广告事件

Page({
  onAdplay(e) {
    console.log('onAdplay', e)
  },
  onAdload(e){
    console.log('onAdload', e)
  },
  onAdclose(e) {
    console.log('onAdclose', e)
  },
  onAdError(e) {
    console.log('onAdError', e)
  },
})

广告预加载

开发者可以调用 wx.preloadVideoAd 的方式进行广告的预加载


const adUnitId1 = 'xxx'
const adUnitId2 = 'xxx'
wx.preloadVideoAd([adUnitId1, adUnitId2])

错误码

错误码是通过bindaderror回调获取到的错误信息,前贴广告再普通广告组件ad错误码基础上新增了以下错误码。

代码 异常情况 解决方案
3001 命中频控策略 按照没有广告处理
3002 命中频控策略 按照没有广告处理
3003 命中频控策略 按照没有广告处理
3004 命中频控策略 按照没有广告处理

注意事项

1、支持视频预加载能力:文档地址

2、仅支持同层渲染模式下的video组件。

3、开发者可监听bindadplay事件获取广告播放状态,做出相应处理。

4、ad-unit-id不支持异步设置,只支持设置在wxml或者js文件的data属性里,通过setData设置的无效。

5、全屏模式下不展示视频前贴广告。