一、引入模块
插件模块通过全局变量注入,可通过以下方式导入:
require:
import:
或是通过html引入等立即执行的方式引入即可。
二、创建模块实例:
传入参数定义如下:
appid: 当前游戏的appid,注意为字符串类型
openid: 当前玩家的openid(上报统计需要),注意为字符串类型
debug: 为true时会打出模块内部逻辑log,便于功能验证调试
env: 插件访问后台的环境,pre为预发布,prod为正式,默认为prod(1.0.1版本开始支持),请在开发测试阶段,使用预发布环境(pre)进行调试,发布到外网前,使用正式环境(prod)或不传env参数验证后再发布外网。
forceOpen: 当自测时需要强制显示图标,而后台配置为关闭时使用,请勿在外网小游戏中使用(1.0.1版本开始支持)
onReady: 初始化回调函数(可选参数,1.0.4版本后支持。也可在构建实例对象后设置,见下小节说明)
platform: 可选参数,默认为wx,当在QQ玩一玩中使用需设置为qq。(1.0.6版本支持此参数)
三、模块初始化
设置模块的onReady回调,回调内的参数为显示开关和首个显示的游戏,在回调中实现图标点击事件的监听,点击事件回调中,调用模块实例的jumpToCurrentGame方法,跳转到对应的小游戏。
游戏侧需要根据显示开关,控制浮动图标显示或隐藏。
关于回调中的game参数,game.icon为远程url,游戏方需远程加载该url的图片,然后显示在图标上,因为图片是循环变换,因此建议游戏方做好缓存管理。
下图是cocos-creator下的例子:
四、设置图片切换的回调
当用户点击图标后,会触发模块的一个change事件,游戏侧需要设置onChange回调,在回调中获取切换的下一个显示游戏,更改图标的图片显示。
关于图标的大小,请以原图的大小进行显示,图片最大的宽高为宽100像素,高130像素,如果图片宽高超出了这个范围,以宽100像素,高130像素的上限控制大小显示即可,不要固定图标的大小,否则可能出现拉伸变形。
下面是宽高设置的做法:
由于插件1.0.6版本开始支持后台配置定时轮播,因此配置轮播时会定时调用onChange方法,请游戏方注意如果因切换游戏场景,onChange回调内引用的变量、节点可能会被销毁,请游戏方在回调中做好判断,避免抛出运行错误。
或者若切换到无插件节点的场景前,可以调用下面方法暂停轮播(1.0.6版本及以上):
切换回到插件的场景时,若游戏保存了插件实例,则可调用插件的resumeLoop方法恢复轮播,若已销毁,则重新创建实例。
样例demo: http://dldir3.qq.com/minigamefile/mgplugin_new/recommender-example.zip
该demo为cocos-creator引擎项目,打包成小游戏时请设置打包的appid为自身的开发游戏appid,该项目仅供实现参考,里面的插件版本不是最新的,请勿直接用于游戏项目。
五、上报验证
新版插件简化了UI,因此上报逻辑也简化了许多,插件初始构造实例时,会对首个游戏进行曝光上报,之后每次调用jumpToCurrentGame,会进行当前游戏的点击上报以及下一个游戏的曝光上报(逻辑上会切换到下个游戏)。
游戏方在debug模式下查看上报逻辑log验证即可:
如果插件方未查询到上报数据,请按如下步骤协助定位问题:
1.查看debug模式下的log,展开上报log的数据以及回包数据,查看回包是否正确(request:ok)
2.检查传入的openid和appid是否为字符串
3.和运营核实,查询的appid与传入的appid是否一致。
3.如上述正常,请将展开数据后的log截图发给开发。
六、轮播功能验证
首先打开插件的log开关(debug参数设为true),接入插件后,启动游戏,在开发者工具或者手机的调试模式中的vconsole查看插件log。可从log中看到轮播开关是否打开的信息:
若开关打开,则会启动轮播,目前的轮播策略是,轮播开关打开时,图标不会随用户的点击行为而切换,而是以后台配置的固定时间间隔进行定时切换。
切换时可看到相关log信息:
若配置游戏中有QQ游戏合集小程序,则小程序图标显示的时间为插件后台独立配置:
七、测试流程
1.接入前游戏方须和插件方沟通相应的推荐游戏配置,插件方运营在预发布环境为游戏配置数据。
2.然后游戏方使用预发布环境接入测试(构造参数的env参数为pre),打开debug参数开关,生成体验包给插件方验收(若未加预发布环境的按钮域名,需打开调试模式)。
3.测试验收通过后,插件方运营配置数据到正式环境,游戏方再转到正式环境(构造函数的env参数为prod)进行最后的验证。