微信小游戏联运对接文档1.0

目录

游戏联运对接文档1.0

1、一 接入必读

1.1、SDK-总体机制

术语表：

总体架构：

1 登陆流程

2 充值流程

1.2、SDK-接入流程

1.3、注意事项

2、二 服务端接入

2.1、1-登陆认证

2.2、2-支付通知

2.3、3-角色信息上报

2.4、4-游戏服务器开发要点

通信协议：

user_token 验证注意事项：

充值结果回调注意事项：

2.1、DEMO

2.1.1、PHP

2.1.2、JAVA

3、三 客户端JS接入

3.1、配置导入微信小程序SDK

3.2、调用 SDK 初始化

3.3、调用 SDK 登录

3.4、上传用户信息

3.5、SDK 切换支付

3.6、查询支付结果

3.7、获取分享内容

3.8、分享上报

3.9、上传角色信息

3.10、敏感词检测

3.11、敏感图片检测  

3.12、角色支付切换

1、一 接入必读

1.1、SDK-总体机制

术语表：

总体架构：

"SDK"分为

· "SDK"（集成于游戏中)、

· "SDK 服务器"两部分。

"游戏客户端" (内含”SDK”)、"游戏服务器" "SDK 服务器"之间的关系如下图所示： 

1 登陆流程

2 充值流程

备注

1.2、SDK-接入流程

1.3、注意事项

2、二 服务端接入

2.1、1-登陆认证

简要描述： 

· 验证登陆user_token 是否有效

· 请求URL： https:// mp.cceuc.com/cp/user/check 

· https://【域名】/cp/user/check

请求方式： (UTF-8)

· HTTP POST

接口说明：

请求方：

· 游戏服务器

响应方：

· SDK服务器

请求参数： 

请求示例： 

POST参数：

app_id=1&mem_id=23&user_token=rkmi2huqu9dv6750g5os11ilv2&sign=4753dce3ae736e7f894ebcc6cd3cff7a

假定app_key= de933fdbede098c62cb309443c3cf251

sign 的签名规则：md5(app_id=...&mem_id=...&user_token=...&app_key=...)

(替换...为实际值)

签名原文：

app_id=1&mem_id=23&user_token=rkmi2huqu9dv6750g5os11ilv2&app_key=de933fdbede098c62cb309443c3cf251

sign=md5(app_id=1&mem_id=23&user_token=rkmi2huqu9dv6750g5os11ilv2&app_key=de933fdbede098c62cb309443c3cf251)

md5加密：

echo -n "app_id=1&mem_id=23&user_token=rkmi2huqu9dv6750g5os11ilv2&app_key=de933fdbede098c62cb309443c3cf251"|md5sum

加密结果：4753dce3ae736e7f894ebcc6cd3cff7a

返回示例（JSON返回）

返回参数说明 

状态码说明 

2.2、2-支付通知

简要描述： 

· 平台充值成功后通知游戏服务器 请求接口

请求URL： 

· 即充值结果通知地址，CP提供。游戏接入时，录入到的游戏平台中。

请求方式：(UTF-8)

· HTTP POST

接口说明：

请求方：

· SDK 服务器

响应方：

· 游戏服务器

请求参数： 

请求示例： 

POST参数：

app_id=60000&cp_order_id=10000&ext=%E7%A9%BF%E9%80%8F&mem_id=136&order_id=1526983557869000036&order_status=2&pay_time=1526983557&product_id=1&product_name=%E5%85%83%E5%AE%9D&product_price=1.00

假定app_key=c703d4627ae162feb939edcc997ac148

sign 的签名规则：md5(app_id...&cp_order_id...&ext...&mem_id...&order_id...&order_status...&pay_time...&product_id...&product_name...&product_price...&app_key=...)

(替换...为实际值)

签名原文：

app_id=60000&cp_order_id=10000&ext=%E7%A9%BF%E9%80%8F&mem_id=136&order_id=1526983557869000036&order_status=2&pay_time=1526983557&product_id=1&product_name=%E5%85%83%E5%AE%9D&product_price=1.00&app_key=c703d4627ae162feb939edcc997ac148

sign=md5(app_id=60000&cp_order_id=10000&ext=%E7%A9%BF%E9%80%8F&mem_id=136&order_id=1526983557869000036&order_status=2&pay_time=1526983557&product_id=1&product_name=%E5%85%83%E5%AE%9D&product_price=1.00&app_key=c703d4627ae162feb939edcc997ac148)

md5加密：

echo -n "app_id=60000&cp_order_id=10000&ext=%E7%A9%BF%E9%80%8F&mem_id=136&order_id=1526983557869000036&order_status=2&pay_time=1526983557&product_id=1&product_name=%E5%85%83%E5%AE%9D&product_price=1.00&app_key=c703d4627ae162feb939edcc997ac148"|md5sum

加密结果：45347e179eb0dc85cdd4010601b2a960

返回示例:

返回参数说明: 

注意事项:

通知机制:

2.3、3-角色信息上报

简要描述： 

· 上报游戏角色信息到sdk服务器。

· 选接，客户端或者服务端一个端接入即可。

请求URL： 

· https://mp.j8youxi.com/cp/role/report

请求方式： (UTF-8)

· HTTP POST

请求方：

· 游戏服务器

响应方：

· SDK服务器

请求参数： 

请求示例： POST参数：

app_id=1&combat_num=100&event=1&mem_id=23&role_id=1&role_name=xxx&role_level=1&role_vip=1&server_id=1&server_name=xxx&sign=4753dce3ae736e7f894ebcc6cd3cff7a

sign 的签名规则：md5(app_id=...&combat_num=...&event=...&mem_id=...&role_id=...&role_name=...&role_level=...&role_vip=...&server_id=...&server_name=...&app_key=...)

(替换...为实际值)

签名原文：

app_id=1&combat_num=100&event=1&mem_id=23&role_id=1&role_name=xxx&role_level=1&role_vip=1&server_id=1&server_name=xxx&app_key=de933fdbede098c62cb309443c3cf251

最终签名为32位md5小写值：

sign=md5(app_id=1&combat_num=100&event=1&mem_id=23&role_id=1&role_name=xxx&role_level=1&role_vip=1&server_id=1&server_name=xxx&app_key=de933fdbede098c62cb309443c3cf251)

注意：

返回示例（JSON返回）

返回参数说明 

状态码说明 

2.4、4-游戏服务器开发要点

通信协议：

· “SDK 服务器”采用HTTP 协议作为通信协议，

· “游戏服务器”通过构造HTTP 请求（POST方式）向“SDK 服务器”发起接口请求。

user_token 验证注意事项：

· user_token验证应该在客户端接到sdk 登陆成功后，客户端再登陆游戏服务器的时候，游戏服务器请求sdk 服务器验证。

· 在登陆或必要的时候调用，不做无故调用，注意控制调用次数，这个接口做了次数等限制。

充值结果回调注意事项：

在充值完成之后，SDK服务器会回调CP 给的地址。

· *需要校验回调的金额是否跟商品的真实价格一致；

· *需要校验用户是否充值成功；

· *返回值：返回“SUCCESS”表示通知CP成功了，其他错误等情况返回"FAILURE"。

2.1、DEMO

2.1.1、PHP

登陆认证： 

$query_data['user_token'] = 'MsHdZajsOdXhA5y6N3D5l6mfbgDdddsDNFnGUGzJaGzHdxcXBjNDY4aGQO0O0O'; // 获取的user_token

$query_data['mem_id'] = '23'; // 获取的用户ID

$query_data['app_id'] = '1'; // 获取的游戏APPID

$app_key = 'de933fdbede098c62cb309443c3cf251'; // 获取的游戏APPKEY$url ="https://mp.cceuc.com/cp/user/check";

$signstr = "app_id=" . $query_data['app_id'] . "&mem_id=" . $query_data['mem_id'] . "&user_token=" . $query_data['user_token'] . "&app_key=" . $app_key;

$query_data['sign'] = md5($signstr);

/* http请求 */

$rdata = http_post_data($url, $query_data);

if ($rdata) {

    $rdata = json_decode($rdata,true);

    if ('1' == $rdata['status']) {

        // CP操作,请求成功,用户有效

        echo $rdata['data'];

    }

}

// HTTP 数据请求函数

function http_post_data($url, array $query_data) {

    $post_str = http_build_query($query_data);

    $curl = curl_init(); // 初始化curl

    curl_setopt($curl, CURLOPT_URL, $url);

    curl_setopt($curl, CURLOPT_HEADER, 0); // 过滤HTTP头

    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); // 显示输出结果

    curl_setopt($curl, CURLOPT_POST, 1); // post传输数据

    curl_setopt($curl, CURLOPT_POSTFIELDS, $post_str); // post传输数据

    curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 3); // 设置等待时间

    $header = array(

        "Content-Type: application/x-www-form-urlencoded; charset=UTF-8"

    );

    curl_setopt($curl, CURLOPT_HTTPHEADER, $header);

    //https 请求

    if (strlen($url) > 5 && strtolower(substr($url, 0, 5)) == "https") {

        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);

        curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, false);

    }

    $return_content = curl_exec($curl);

    curl_close($curl);

    return $return_content;

}

2.1.2、JAVA

public class CheckLoginDemo {

    public static void main(String[] args) throws Exception {

        String user_token="rkmi2huqu9dv6750g5os11ilv2";// 获取的user_token

        String mem_id="23";// 获取的用户ID

        String app_id="1";// 获取的游戏APPID

        String app_key="de933fdbede098c62cb309443c3cf251";// 获取的游戏APPKEY

        Stringurl="https://mp.cceuc.com/cp/user/check";

        checkLogin(url,user_token,mem_id,app_id,app_key);

    }

    private static void checkLogin(String url, String user_token, String mem_id, String app_id, String app_key) throws Exception{

        StringBuffer buffer=new StringBuffer("app_id=").append(app_id)

                .append("&mem_id=").append(mem_id)

                .append("&user_token=").append(user_token);

        String params=buffer.toString();

        String sign= getMD5(buffer.append("&app_key=").append(app_key).toString());

        params=params+"&sign="+sign;

        System.out.println("params="+params);

        HttpURLConnection conn=null;

        InputStream is=null;

        BufferedReader reader=null;

        OutputStream outputStream;

        try {

            URL murl=new URL(url);

            conn = (HttpURLConnection) murl.openConnection();

            conn.setRequestMethod("POST");

            conn.setConnectTimeout(5 * 1000);

            conn.setReadTimeout(30 * 1000);

            //设置允许打开输出流，默认为不打开

            conn.setDoOutput(true);

            //设置请求头信息，可设置多个

            conn.setRequestProperty("content-type", "application/x-www-form-urlencoded");

            conn.setRequestProperty("Charset", "UTF-8");

            conn.connect();

            //获得输出流，用于往服务器写入数据

            outputStream = conn.getOutputStream();

            outputStream.write(params.getBytes());

            outputStream.flush();

            outputStream.close();

            int code = conn.getResponseCode();

            if(code==HttpURLConnection.HTTP_OK){

                is = conn.getInputStream();

                reader=new BufferedReader(new InputStreamReader(is));

                String line=null;

                StringBuffer dataBuffer=new StringBuffer();

                while ((line=reader.readLine())!=null){

                    dataBuffer.append(line).append("\n");

                }

                //得到联网结果使用json解析出status=1表示登陆校验通过

                System.out.println("联网结果："+dataBuffer.toString());

            }else{

                System.out.println("联网code："+code);

            }

        } catch (Exception e) {

            throw e;

        } finally {

            if(reader!=null){

                reader.close();

            }

            if(is!=null){

                is.close();

            }

            conn.disconnect();

        }

    }

}

3、三 客户端JS接入

3.1、配置导入微信小程序SDK

此对接文档说明如何在微信小程序中集成 huoSdk。

SDK 集成

在创建的项目中，新建一个名为 libs 的目录，将 huosdk-<version>.js 文件拷贝到 libs 目录下，即可完成 SDK 集成。

设置安全通讯域名

登录微信公众平台，在 "设置"->"开发设置" 中配置 request 合法域名：https://mp.cceuc.com

获取参数

从平台处，获取以下参数，用于对接。

SDK 使用

在本地文件中引入 huosdk-<version>.js 文件。

const huoSdk = require('<path>/libs/huosdk-<version>.js')

huoSdk 提供的所有 api 都会返回一个 Promise 对象。

通过对 Promise 对象的成功/失败状态分别绑定相应的处理方法，可以获取 api 的成功/失败返回结果。

3.2、调用 SDK 初始化

请确保在初始化返回成功后，再调用其他 api。

请求方法

huoSdk.init()

请求参数

sdk 中提示框默认参数如下：

{

  showLoading: true,

  loadingParams: {

    title: '加载中',

    mask: true

  },

  showToast: false,

  toastParams: {

    icon: 'none'

  }

}

以上参数除在初始化方法中统一配置以外，还可在其他方法中单独配置。

请求示例

huoSdk.init({

  app_id: 81234609,

  mp_id: 'wx2012342143434'

}).then(res => {

  // do something

})

返回结果

成功状态返回：

失败状态返回：

3.3、调用 SDK 登录

注意：如果需要标识归属渠道或上级玩家，则调用本接口时必须传递 state 参数。

小程序可在 wx.onLaunch() 或 wx.onShow() 获取启动参数中的 query，在 query 参数中携带有 state 信息。

小游戏可在 wx.getLaunchOptionsSync() 或 wx.onShow() 获取启动参数中的 query，在 query 参数中携带有 state 信息。

通过分享消息或路径跳转方式进入，取 query.state 值；通过小程序码扫码方式进入，取 query.scene 值。需要对这两种情况做兼容处理，可查看下文请求示例。

state 信息并非一定会携带，所以此字段非必填字段，但是如果获取到此信息，务必通过本接口传递，否则会丢失归属渠道或上级玩家信息。

在启动参数中获取的 state 和 获取分享内容接口得到的 state 本质相同。不同之处在于，启动参数获取的是其他玩家的标识，获取分享内容接口获取的是自身的标识。

请求方法

huoSdk.login()

请求参数

请求示例

let opts = wx.getLaunchOptionsSync()

// 初始化成功再调起登录

huoSdk.init({

  app_id: APPID,

  mp_id: MPID

}).then(res => {

  huoSdk.login({

    data: {

      // 路径跳转从 state 参数获取，扫码跳转从 scene 参数获取，因此此处需要兼容处理

      state: opts.query.state || opts.query.scene || ''

    }

  }).then(res => {

    // do something

  })

})

返回结果

成功状态返回：

失败状态返回：

3.4、上传用户信息

使用 引导用户主动进行授权操作，通过 bindgetuserinfo 事件上传用户信息。

详细信息可参考：wx.getUserInfo

SDK 不主动上传用户信息，若要更新用户信息，需主动调用此接口。

请求方法

huoSdk.updateUserInfo()

请求参数

请求示例

<button bindgetuserinfo="updateUserInfo" open-type="getUserInfo">授权</button>

updateUserInfo (e) {

  huoSdk.updateUserInfo({

    data: {

      raw_data: e.detail.rawData,

      signature: e.detail.signature,

      encrypted_data: e.detail.encryptedData,

      iv: e.detail.iv

    }

  }).then(res => {

    // do something

  })

}

// 主动上传用户信息，需先校验用户是否开启授权

wx.getSetting({

  success: res => {

    if (res.authSetting['scope.userInfo']) {

      // 用户当前已授权，则可调用 wx.getUserInfo 获取用户最新个人信息

      wx.getUserInfo({

        success: res => {

          huoSdk.updateUserInfo({

            data: {

              raw_data: res.rawData,

              signature: res.signature,

              encrypted_data: res.encryptedData,

              iv: res.iv

            }

          })

        }

      })

    }

  }

})

返回结果

成功状态返回：

失败状态返回：

3.5、SDK 切换支付

此接口会依据管理后台配置，分三种处理情况：

1. 不切换支付：主动调起米大师支付

2. 切换支付：直接跳转（在管理后台设置“直跳”跳转类型）

3. 切换支付：展示二维码，提示玩家扫码打开（在管理后台设置“二维码”跳转类型）

选择“直跳”跳转类型，需要配置 navigateToMiniProgramAppIdList。

如下图

选择“二维码”跳转类型，需要在调用接口时传入主画布对象和离屏画布对象，若未传入画布对象，则不展示二维码，需要接入方对返回数据做处理。

离屏画布需要由游戏绘制到主画布中。清除离屏画布及事件请调用方法 huoSdk.removeOffScreen()。

请求方法

huoSdk.checkPay()

请求参数

请求示例

huoSdk.checkPay({

  data: {

    'order-currency': 'CNY',

    'order-cp_order_id': '10001',

    'order-product_price': 0.01,

    'order-product_id': '1000000001',

    'order-product_cnt': 1,

    'order-product_name': '金币',

    'order-product_desc': '金币',

    'order-ext': '',

    'role-event': '',

    'role-server_id': '',

    'role-server_name': '',

    'role-role_id': '',

    'role-role_name': '',

    'role-role_level': 0,

    'role-role_vip': 0

  }

}).then(res => {

  // do something

})

返回结果

成功状态返回：

失败状态返回：

3.6、查询支付结果

请求方法

huoSdk.mpPayQuery()

请求参数

请求示例

huoSdk.mpPayQuery({

  data: {

    'order-order_id': '10001'

  }

}).then(res => {

  // do something

})

返回结果

成功状态返回：

失败状态返回：

3.7、获取分享内容

通过此接口获取到个人分享码，在转发路径上携带此参数，具体操作详见下文请求示例。

请求方法

huoSdk.getShareInfo()

请求参数

请求示例

huoSdk.getShareInfo({

  data: {

    path: 'pages/box/box'

  }

}).then(res => {

  // 小程序

  this.setData({

    shareInfo: res.data

  })

  // 小游戏

  wx.onShareAppMessage(function () {

    return {

      title: res.data.title,

      imageUrl: res.data.image,

      query: `state=${res.data.state}`

    }

  })

  wx.showShareMenu()

})

// 小程序

onShareAppMessage: function (opt) {

  return {

    title: 'share title',

    imageUrl: 'share img src',

    path: `/pages/a/b?state=${this.data.shareInfo.state}`

  }

}

返回结果

成功状态返回：

失败状态返回：

3.8、分享上报

由于官方接口能力调整，此接口只能统计用户触发分享点击，而非用户成功分享。在用户触发分享操作时调用。

请求方法