联系我们
荆秀网

客户端接入

客户端接入 WSS 服务分为两个部分：

  • 服务端：生成身份鉴权令牌（JWT Token）放置在客户端 HTML Javascript 代码中备用
  • 客户端：连接 WSS 服务器，递交令牌申明合法身份建立对应用的事件监听

服务端：生成身份鉴权令牌

WSS 服务是一个公开在广域互联网上的实时数据推送服务，因此在创建订阅者之前，需要解决一个客户端身份鉴权的问题。

WSS 服务使用 JWT(JSON Web Tokens) JWT 官网 来进行令牌鉴权（鉴别权限），因此需要接入方在连接 WSS 服务之前生成身份鉴权令牌。

接入方在生成身份鉴权令牌的数据包 payload 需要以下三个参数，均为必填项；可增加其他业务参数，WSS 在鉴权成功后会返回全部参数。

  • Payload
    • app my_test_app 应用名
    • uid 71 客户端用户唯一ID
    • exp 18623523110 令牌过期时间戳
1
2
3
4
5
6
7
8
9
<?php
$payload = array(
    'app' => 'my_test_app',
    'uid' => 71,
    'exp' => time() + 86700
);
$secretKey = "1Ufd******PitR"; // 超级密钥
$token = \JWT::encode($payload, $secretKey, "HS256"); // JWT 加密参数恒定为 HS256
?>

客户端：递交令牌申明合法身份建立连接

客户端运行环境为兼容主流内核（如：Trident内核／Gecko内核／WebKit内核／Presto内核）的 Web 浏览器中，最佳调用方式是使用 Javascript 脚本。

WSS 服务在客户端接入推荐使用 Socket.IO 官网 代码库，此代码库使用起来已经相当简单了，为了进一步方便使用，WSS 封装了连接、鉴权、监听事件的工厂方法，直接引入即可使用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
<script src="js/wss.class.js?version=3.4.6"></script>
<script>
    $(function () {
        /**
         * 连接参数，以下示例均为必填项
         * update @ 2017-05-20
         */
        var config = {
            "debug": true, // 打开调试模式，会输出连接和鉴权信息
            "info":  document.getElementById('result'), // 指定显示调试信息的元素容器
            "url":   "WSS WebSocket Service Url",   // wss 服务器 url
            "app":   "my_test_app",   // 自己创建的 app name，用于域权限验证
            "jwt":   "<?php echo $token; ?>", // 使用 JWT 制作的用户令牌，用于用户身份验证
            "listener": []  // 待注册的监听事件，数组内放置多个监听函数
        };
        // 注册监听函数，可以注册多个
        config['listener'].push({
            "event":    "client_price:update",
            "callback": function (res) {
                console.log('[CLIENT][INFO] 注册监听事件 receive [client_price:update]:', res);
            }
        });
        config['listener'].push({
            "event":    "action_341:append",
            "callback": function (res) {
                console.log('[CLIENT][INFO] 注册监听事件 receive [action_341:append]:', res);
            }
        });
        // 初始化 wss 实例
        var initWssServ = function (config) {
            var _wss = false;
            if (!WSS) {
                console.log('[CLIENT][ERR] WSS is not defined');
                alert('WSS is not defined');
                return false;
            };
            try {
                _wss = new WSS(config);
            } catch(e) {
                console.log('[CLIENT][ERR] e', e);
                alert(e.message);
                return false;
            };
            return _wss.instance;
        };
        var _wss = initWssServ(config);
        if (_wss) {
            // 连接成功
            //console.log('[CLIENT][INFO] 连接成功');
            // 除了上面注册监听事件以外
            // 还可以继续建立新的监听
            _wss.on('auction_begin:update', function (res) {
                console.log('[CLIENT][INFO] 继续监听事件 receive [auction_begin:update]:', res);
            });
            // 可以建立多个监听事件
            _wss.on('auction_close:update', function (res) {
                console.log('[CLIENT][INFO] 继续监听事件 receive [auction_close:update]:', res);
            });
        } else {
            throw new Error("[CLIENT][ERR]错误：连接 WSS 服务器失败！请刷新页面重新尝试！");
        };
    });
</script>

WSS 工厂类返回的是 Socket 对象

Socket.IO 绑定事件使用 Socket.on() 方法，解除绑定事件使用 Socket.off() 方法，详见其 官网 Docs Client API。