总概

我们依据H5小游戏框架实现一套协议，对于新加入的渠道只需根据我们提供的文档进行接入，即可完成H5小游戏在自己渠道APP的适配。

第三方渠道的接入流程，大致包括：

①在第三方渠道APP的webview中提供window.wanba接口

②修改UserAgent以供进行渠道识别

③登录态按指定命名规则设置cookies

④联系我方产品去后台配置渠道的appid与确认ZZ配置表内容

⑤支付接入

⑥渠道方自测，主要包括进入游戏集合页（登录功能，拉取最近在玩、新品尝鲜、精品力荐、排行榜游戏数据）和打开游戏（包括微信登录态和QQ登录态），

最后是Q&A

流程说明

1.window.wanba接口

我们要求渠道商独立开发并部署一个独立的注入JS文件在腾讯的服务器上，用于转换客户端提供的js接口（建议腾讯外部渠道在前期接入过程中，ZZ配置表的注入js地址先随意使用一个腾讯域名的url并本地代理到指定js文件，等接入基本完成后再正式部署在我们的服务器上并更改ZZ配置表的注入js地址）。注入该JS文件后webview需要提供包括打开、关闭webview，拉起分享面板，弹出提示等能力的方法或属性，并将其挂载在window.wanba上。我们会统一将window.wanba进一步封装成mqq方法，供小游戏开发商调用，示意图如下：

在文档末尾技术细节部分有window.wanba接口列表以及相应说明。如果客户端已经在window.wanba上提供了相应的JS接口，则不需要提供注入JS文件进行转换。参考示例：https://webcdn.m.qq.com/active/wanba.js

2.渠道识别

我们要求渠道商在该渠道App的WebView的 UserAgent都包含thirdChannel_XXX/X.X关键字（如thirdChannel_smallsheep/1.0），其中'thirdChannel'为QQ小游戏新加入渠道的统一识别方式，'XXX'为APP名称，'X.X'为版本号(三个都不可缺失！！！)。我们将对渠道识别的工作进行收归与优化，并根据UserAgent中thirdChannel的关键字来判断是否走新的统一接入逻辑，且保留了APP名称，用于罗盘上报和游戏开发商开发渠道专属活动。

3.cookies

渠道方需要把有效的登录态票据种在.qq.com域名下的webview。所有渠道cookie的name值保持统一，包括accesstoken、appid、openid、logintype以及相应的third版本的cookie（只是key值不一样，value相同。即access_token和third_access_token的值是相同的）

cookies：

name	value类型	补充说明
access_token	String
appid	String	qq或者微信登录授权后的appid
openid	String
logintype	String	QQ登录态值为'qq'；微信登录态值为'wx'
third_access_token	String
third_appid	String
third_openid	String
third_logintype	String	QQ登录态值为'qq'；微信登录态值为'wx'

如无登录态，进入游戏大厅和单个小游戏的投放链接都会触发window.wanba.loginByQQorWeixin方法，渠道方登录成功后也需要把有效的登录态票据种在cookie中。

4.配置appid和ZZ配置表

新渠道在接入前，需要联系我方产品在后台配置新渠道appid。此外，还需配置两张ZZ配置表，其中表1主要包括渠道方相关信息，由渠道方和我方产品协商后完成配置表；表2主要包括domain、via和游戏配置，由我方产品完成配置。如果不需要游戏大厅页面则可以忽略表2

表1包含内容：

	name	补充说明
1	APPCN	APP中文名称
2	APP	APP英文名称（要和UA中的third_XXX保持一致）
3	appid	QQ登录态appid
4	injectJSUrl	第三方渠道提供注入js文件，然后部署在腾讯的服务器上（可以有多个）。接入前期先用https://test.qq.com/wanba/wanba.js 提供给我方产品，使用代理进行开发。所有测试完成后，再提供正式的js文件或者地址。
5	qqDomain	qq登录态domain
6	wxDomain	wx登录态domain
7	via	via
8	wxappid（好像暂时不需要）	从微信中拉起APP需要wxappid
9	invokeFlag	是否支持从其他APP（包括微信）拉起该渠道。配置为true则支持(同时需要支持window.wanba.invokethirdChannel，详情见window.wanba接口列表接口⑩)；配置为false则拉起手Q打开游戏
10	config	作为url参数从ZZ配置系统拉取不同的游戏配置（主要是新品尝鲜、精品力荐、排行榜三个模块）
11	floatPonitList	多选框，选择圆点浮标支持的能力（分享share，退出quit，发送桌面快捷方式desktop）

表2包含内容：

name	补充说明
qq-domain	qq-domain
wx-domain	wx-domain
via	via
精品力荐	推荐的小游戏配置
排行榜	排行榜的小游戏配置
新品尝鲜	新推出小游戏配置

5.测试

我们会提供游戏大厅地址： https://h5.qzone.qq.com/h5plus/thirdChannelGamecenter?config1=1407&config2=XXX 。其中参数config1固定为1407， config2的值由我方产品给的ZZ配置表序号确定（即ZZ配置表1）。也可以打开单个游戏的投放链接,例如：https://h5.qzone.qq.com/app/open/1107225060/home?_proxy=1&_wv=145191&via=H5.NEWSAPPFAST.QQ&config1=1407&config2=2 ，单个游戏的投放链接也需要找我方产品处获得。

完成前面五个步骤后，渠道方可以尝试进入游戏大厅并测试游戏的进入、分享、拉起支付等功能是否正常。如遇到问题，则根据相应的errorpage或者弹出提示定位问题。

新方案推出前期的测试工作则由渠道方和我方共同完成，方案稳定后主要由渠道方自己完成。

主要需要测试的内容有：

1.游戏大厅是否进入正常，无登录态的情况是否能拉起登录。（不需要游戏大厅可以跳过）

2.游戏大厅里最近在玩拉的数据是否正常，不正常可以在大厅链接后带&checkMode=1校验cookie、ua等信息（此时只校验，不会拉起登录）

3.从游戏大厅进入游戏是否正常

4.“捕了个鱼”等横屏游戏是否横屏

5.游戏内的浮点包含的退出、分享、发送到桌面等能力是否生效

6.进入游戏后能否拉起充值支付

7.https://h5.qzone.qq.com/app/open 域名的单个游戏链接进入是否正常，没有登录的情况是否能拉起登录态，以及上面4-6的能力是否正常。如果不正常可以在链接后带&checkMode=1校验cookie、ua等信息（此时只校验，不会拉起登录）

技术细节

1.window.wanba接口列表

不同渠道可以提供的window.wanba接口不同，如果没有相应的能力则提示unavailable。其中*表示必须提供接口。

1)window.wanba.loginByQQorWeixin(*)

使用说明

拉起登录面板，可以选择手Q或者微信登录

参数说明

loginByQQorWeixin(succCallback,failCallback)

名称	类型	描述	是否必须
succCallback	Function	登录成功回调函数	是
failCallback	Function	登录失败回调函数	是

example

window.wanba.loginByQQorWeixin(function () {
    alert('登录成功');
    location.reload();
}, function () {
    alert('登录失败');
    window.wanba.closeView();
});

2)window.wanba.openView(*)

使用说明

打开新的webview，不带isFullScreen参数默认全屏打开。

参数说明

openView(url, isFullScreen)

名称	类型	描述	是否必须
url	String	需要打开的url	是
isFullScreen	Boolean	是否全屏打开	否

example

window.wanba.openView('https://www.test.com/');
window.wanba.openView('https://www.test.com/', false);

3)window.wanba.closeView()

使用说明

关闭当前webview

example

window.wanba.closeView();

4)window.wanba.showShareMenu(*)

使用说明

显示分享菜单

参数说明

showShareMenu(params, callback)

名称	类型	描述	是否必须
params	Object	分享消息参数	是
callback	Function	注册回调	是

params：

名称	类型	描述	是否必须
title	String	分享标题	是
desc	String	分享消息摘要	是
image_url	String	消息左侧缩略图url。图片推荐使用正方形，宽高不够时等比例撑满，不会变形。注意：图片最小需要200 * 200，否则分享到Qzone时会被Qzone过滤掉。	是
share_url	String	点击分享消息后的跳转url	是

callback(result)：

名称	类型	描述	是否必须
result	Number	返回返回码	是

example

window.wanba.showShareMenu({
    title: '小游A',
    desc: '大家一起来玩吧',
    image_url: 'https://qzonestyle.gtimg.cn/test.png',
    share_url: 'https://www.test.com/'
}, function (result) {
    var retCode = result;
    if (retCode === 0) {
        console.log('分享成功');
    } else {
        console.log('网络出现了一点问题');
    }
});

5)window.wanba.showTextTips(*)

使用说明

弹出文本的toast提示，2秒后消失

example

window.wanba.showTextTips('弹出一个提示');

6)window.wanba.changeRotate(*)

使用说明

变成横屏模式，第三方渠道要提供相应横屏的能力。（横屏小游戏的游戏开发商一般自己会尝试横屏，但在某些渠道开发商会横屏失败。不管游戏能否横屏，我方都会在打开游戏后调用window.wanba.changeRotate接口）

建议渠道方开始接入后，视打开游戏（横屏游戏可以找我方产品提供，例如“捕了个鱼”）的具体情况来决定是否提供这个能力，如果可以横屏则不需要准备此接口；小游戏不能横屏则必须提供此接口。

example

window.wanba.changeRotate();

7)window.wanba.pageVisibility

使用说明

查询页面的可见性。当当前可见view/activity不是本页面，或应用退到后台时，此接口返回false，否则返回true。

参数说明

pageVisibility(callback)

名称	类型	描述	是否必须
callback(result)	Function	注册回调	是

result：

名称	类型	描述	是否必须
result	Boolean	页面可见返回 true 不可见返回 false	是

example

window.wanba.pageVisibility(function(r){
    console.log("visible ?", r);
});

8)window.wanba.addShortcut

使用说明

生成桌面快捷方式图标

参数说明

addShortcut(params)

名称	类型	描述	是否必须
params	Object	分享消息参数	是

params：

名称	类型	描述	是否必须
title	String	标题，缺省的话就取当前页面的title	是
icon	String	快捷方式图标，可以缺省，使用手Q默认icon	是
url	String	点击快捷方式跳转的目标url，不可缺省	是
callback(result)	Function	回调函数	否

result：

名称	类型	描述	是否必须
result	Object	返回对象	是

result.ret:

名称	类型	描述
0	Number	创建桌面快捷方式成功
-1	Number	url字段为空
-2	Number	终端拿到的json格式解析出错
-3	Number	icon字段下载到的数据为空，或者下载到的不是图片数据

example

window.wanba.addShortcut({
    title: document.title,
    icon: appicon,
    url: jumpUrl,
    callback: function (result) {
        if (Number(result.ret, 10) === 0) {
            alert('创建桌面快捷方式成功！');
        } else {
            alert('创建桌面快捷方式失败！');
        }
    }
})

9)window.wanba.getNetworkInfo

使用说明

查询网络状态

参数说明

getNetworkInfo（callback）

名称	类型	必选	描述
callback(result)	Function	是	回调函数

result：

名称	类型	必选	描述
result	Number	是	结果可选值： `-1`: Unknown 未知类型网络 `0`: NotReachable `1`: ReachableViaWiFi `2`: ReachableVia2G `3`: ReachableVia3G `4`. 4G

example

 window.wanba.getNetworkType(function(result){
     alert(result);
 });

10)window.wanba.invokethirdChannel

使用说明

当分享到手Q、微信或者其他app时，点击分享链接。此时调用window.wanba.invokethirdChannel ，试图拉起渠道方app打开游戏。通常是通过schema实现（微信需要单独处理）

参数说明

invokethirdChannel（url）

名称	类型	必选	描述
url	String	是	拉起APP后打开的url

example

 window.wanba.invokethirdChannel(encodeURIComponent(url));

Q&A

Q1：为什么已经在cookies种下登录态（third_openid等），进入大厅还提示登陆？

A1：和我方产品沟通，是否将在后台配置了新渠道的appid。

Q2：为什么进入游戏后提示如下图？

A2：和我方产品沟通，ZZ配置中的渠道英文名称（third_XXX）与新渠道的UA是否不一致。

Q3：为什么进入游戏后提示如下图（“鱼死网破，我已经尽力了”）？提示“第三方服务器忙”或者“appid不存在”。

A3：”第三方服务器忙“，通常是拉取游戏开放商的html失败。”Appid不存在“，通常是该游戏未上架或者上架错误。以上情况均可以和我方产品沟通，联系开发商处理或者下架该款游戏。

Q4：第三方渠道提供注入js文件的url地址有何要求？

A4：js文件不能直接部署在域名下面，比如https://XXXX.com/wnlbridge.js 。至少要在某路径下，如https://XXXX.com/wanba/wnlbridge.js

Q5：对于webview有何要求？

A5：推荐接入腾讯 tbs。（有渠道反馈之前有的小游戏进入有问题，有的没问题。接入tbs后全部恢复正常。具体接入方法需要去找相关文档）

Q6：关于登录态

A6：如果App内用户已使用微信登录或者QQ登录，然后跳转到小游戏页面。此时只需要保证当前页面cookie包含我们需要的字段就不需要重新登录。登录态有效期有限，需要app这边来维护，微信和QQ都有续期机制

Q7：支付时出现以下情况

A7：参考https://wiki.midas.qq.com/post/index/1/32/152/0 处理

Q8：可以不用提供js文件么?

A8：基本上都需要。当客户端jsbrige直接封装成window.wanba的方法时，则不需要js文件

空间小游戏

空间 · 小游戏

总概

流程说明

1.window.wanba接口

2.渠道识别

3.cookies

4.配置appid和ZZ配置表

5.测试

技术细节

1.window.wanba接口列表

Q&A