Wafer client SDK
Switch branches/tags
Nothing to show
Clone or download
Latest commit bc781f2 Jun 19, 2018

README.md

微信小程序客户端腾讯云增强 SDK

Build Status Coverage Status License

本 项目是 Wafer2 的组成部分,为小程序客户端开发提供 SDK 支持会话服务和信道服务。

SDK 获取与安装

解决方案 Demo 已经集成并使用最新版的 SDK,需要快速了解的可以从 Demo 开始。

如果需要单独开始,本 SDK 已经发布为 bower 模块,可以直接安装到小程序目录中。

npm install wafer2-client-sdk

安装之后,就可以使用 require 引用 SDK 模块:

var qcloud = require('./node_modules/wafer2-client-sdk/index.js');

会话服务

会话服务让小程序拥有会话管理能力。

登录

由于微信的 wx.getUserInfo 不再弹窗授权,得修改为 button 弹窗获取用户信息。为此我们提供了新的 API 实现,具体可参考:https://github.com/tencentyun/wafer2-quickstart/issues/10 的说明

注意 2.0 版本以上的 Client SDK 需配合 1.4.x 以上版本的 Node.js SDK 或者,2.2.x 以上版本的 PHP SDK。

// wxml
<button open-type="getUserInfo" lang="zh_CN" bindgetuserinfo="doLogin">获取用户信息</button>

// js
doLogin: function () {
    const session = qcloud.Session.get()

    if (session) {
        // 第二次登录
        // 或者本地已经有登录态
        // 可使用本函数更新登录态
        qcloud.loginWithCode({
            success: res => {
                this.setData({ userInfo: res, logged: true })
                util.showSuccess('登录成功')
            },
            fail: err => {
                console.error(err)
                util.showModel('登录错误', err.message)
            }
        })
    } else {
        // 首次登录
        qcloud.login({
            success: res => {
                this.setData({ userInfo: res, logged: true })
                util.showSuccess('登录成功')
            },
            fail: err => {
                console.error(err)
                util.showModel('登录错误', err.message)
            }
        })
    }
}

本 SDK 需要配合云端 SDK 才能提供完整会话服务。通过 setLoginUrl 设置登录地址,云服务器在该地址上使用云端 SDK 处理登录请求。

setLoginUrl 方法设置登录地址之后会一直有效,因此你可以在微信小程序启动时设置。

登录成功后,可以获取到当前微信用户的基本信息。

注意,以下接口已经被微信废弃,但为了兼容暂时没有去除,请使用上文所说的按钮获取用户信息样式 微信官方公告:https://developers.weixin.qq.com/blogdetail?action=get_post_info&lang=zh_CN&token=83045995&docid=0000a26e1aca6012e896a517556c01

登录可以在小程序和服务器之间建立会话,服务器由此可以获取到用户的标识和信息。

var qcloud = require('./bower_components/qcloud-weapp-client-sdk/index.js');

// 设置登录地址
qcloud.setLoginUrl('https://199447.qcloud.la/login');
qcloud.login({
    success: function (userInfo) {
        console.log('登录成功', userInfo);
    },
    fail: function (err) {
        console.log('登录失败', err);
    }
});

请求

如果希望小程序的网络请求包含会话,登录之后使用 request 方法进行网络请求即可。

qcloud.request({
    url: 'http://199447.qcloud.la/user',
    success: function (response) {
        console.log(response);
    },
    fail: function (err) {
        console.log(err);
    }
});

如果调用 request 之前还没有登录,则请求不会带有会话。request 方法也支持 login 参数支持在请求之前自动登录。

// 使用 login 参数之前,需要设置登录地址
qcloud.setLoginUrl('https://199447.qcloud.la/login');
qcloud.request({
    login: true,
    url: 'http://199447.qcloud.la/user',
    success: function (response) {
        console.log(response);
    },
    fail: function (err) {
        console.log(err);
    }
});

关于会话服务详细技术说明,请参考 Wiki

信道服务

信道服务小程序支持利用腾讯云的信道资源使用 WebSocket 服务。

// 创建信道,需要给定后台服务地址
var tunnel = this.tunnel = new qcloud.Tunnel('https://199447.qcloud.la/tunnel');

// 监听信道内置消息,包括 connect/close/reconnecting/reconnect/error
tunnel.on('connect', () => console.log('WebSocket 信道已连接'));
tunnel.on('close', () => console.log('WebSocket 信道已断开'));
tunnel.on('reconnecting', () => console.log('WebSocket 信道正在重连...'));
tunnel.on('reconnect', () => console.log('WebSocket 信道重连成功'));
tunnel.on('error', error => console.error('信道发生错误:', error));

// 监听自定义消息(服务器进行推送)
tunnel.on('speak', speak => console.log('收到 speak 消息:', speak));

// 打开信道
tunnel.open();
// 发送消息
tunnel.emit('speak', { word: "hello", who: { nickName: "techird" }});
// 关闭信道
tunnel.close();

信道服务同样需要业务服务器配合云端 SDK 支持,构造信道实例的时候需要提供业务服务器提供的信道服务地址。通过监听信道消息以及自定义消息来通过信道实现业务。

关于信道使用的更完整实例,建议参考客户端 Demo 中的三木聊天室应用源码

关于信道服务详细技术说明,请参考 Wiki

API

setLoginUrl

设置会话服务登录地址。

语法

qcloud.setLoginUrl(loginUrl);

参数

参数         类型 说明
loginUrl string 会话服务登录地址

login

登录,建立微信小程序会话。

语法

qcloud.login(options);

参数

参数         类型 说明
options     PlainObject   会话服务登录地址
options.success () => void 登录成功的回调
options.error (error) => void 登录失败的回调

request

进行带会话的请求。

语法

qcloud.request(options);

参数

参数         类型 说明
options     PlainObject   会话服务登录地址
options.login bool         是否自动登录以获取会话,默认为 false
options.url   string       必填,要请求的地址
options.header PlainObject 请求头设置,不允许设置 Referer
options.method string     请求的方法,默认为 GET
options.success (response) => void 登录成功的回调。
  • response.statusCode:请求返回的状态码
  • response.data:请求返回的数据
options.error (error) => void 登录失败的回调
options.complete () => void 登录完成后回调,无论成功还是失败

Tunnel

表示一个信道。由于小程序的限制,同一时间只能有一个打开的信道。

constructor

语法
var tunnel = new Tunnel(tunnelUrl);

参数

参数         类型 说明
tunnelUrl   String   会话服务登录地址

on

监听信道上的事件。信道上事件包括系统事件和服务器推送消息。

语法
tunnel.on(type, listener);
参数
参数         类型 说明
type       string     监听的事件类型
listener     (message?: any) => void 监听器,具体类型的事件发生时调用监听器。如果是消息,则会有消息内容。
事件
事件 说明
connect 信道连接成功后回调
close 信道关闭后回调
reconnecting 信道发生重连时回调
reconnected 信道重连成功后回调
error 信道发生错误后回调
[message]   信道服务器推送过来的消息类型,如果消息类型和上面内置的时间类型冲突,需要在监听的时候在消息类型前加 @
*           监听所有事件和消息,监听器第一个参数接收到时间或消息类型 

open

打开信道,建立连接。由于小程序的限制,同一时间只能有一个打开的信道。

语法
tunnel.open();

emit

向信道推送消息。

语法
tunnel.emit(type, content);
参数
参数         类型 说明
type       string       要推送的消息的类型
content any 要推送的消息的内容

close

关闭信道

语法
tunnel.close();

LICENSE

MIT