# wafer2-client-sdk **Repository Path**: mirrors_tencentyun/wafer2-client-sdk ## Basic Information - **Project Name**: wafer2-client-sdk - **Description**: Wafer client SDK - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-08-18 - **Last Updated**: 2026-01-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 微信小程序客户端腾讯云增强 SDK [![Build Status](https://travis-ci.org/tencentyun/wafer-client-sdk.svg?branch=master)](https://travis-ci.org/tencentyun/wafer-client-sdk) [![Coverage Status](https://coveralls.io/repos/github/tencentyun/wafer-client-sdk/badge.svg?branch=master)](https://coveralls.io/github/tencentyun/wafer-client-sdk?branch=master) [![License](https://img.shields.io/github/license/tencentyun/wafer-client-sdk.svg)](LICENSE) 本 项目是 [Wafer2](https://github.com/tencentyun/wafer) 的组成部分，为小程序客户端开发提供 SDK 支持会话服务和信道服务。 ## SDK 获取与安装 [解决方案 Demo](https://github.com/tencentyun/wafer2-quickstart) 已经集成并使用最新版的 SDK，需要快速了解的可以从 Demo 开始。 如果需要单独开始，本 SDK 已经发布为 bower 模块，可以直接安装到小程序目录中。 ```sh npm install wafer2-client-sdk ``` 安装之后，就可以使用 `require` 引用 SDK 模块： ```js var qcloud = require('./node_modules/wafer2-client-sdk/index.js'); ``` ## 会话服务 [会话服务](https://github.com/tencentyun/wafer-solution/wiki/%E4%BC%9A%E8%AF%9D%E6%9C%8D%E5%8A%A1)让小程序拥有会话管理能力。 ### 登录 由于微信的 `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 // 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](#setLoginUrl) 设置登录地址，云服务器在该地址上使用云端 SDK 处理登录请求。 > `setLoginUrl` 方法设置登录地址之后会一直有效，因此你可以在微信小程序启动时设置。 登录成功后，可以获取到当前微信用户的基本信息。 > 注意，以下接口已经被微信废弃，但为了兼容暂时没有去除，请使用上文所说的按钮获取用户信息样式 > 微信官方公告：https://developers.weixin.qq.com/blogdetail?action=get_post_info&lang=zh_CN&token=83045995&docid=0000a26e1aca6012e896a517556c01 登录可以在小程序和服务器之间建立会话，服务器由此可以获取到用户的标识和信息。 ```js 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](#request) 方法进行网络请求即可。 ```js qcloud.request({ url: 'http://199447.qcloud.la/user', success: function (response) { console.log(response); }, fail: function (err) { console.log(err); } }); ``` 如果调用 `request` 之前还没有登录，则请求不会带有会话。`request` 方法也支持 `login` 参数支持在请求之前自动登录。 ```js // 使用 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](https://github.com/tencentyun/wafer-solution/wiki/%E4%BC%9A%E8%AF%9D%E6%9C%8D%E5%8A%A1)。 ## 信道服务 [信道服务](https://github.com/tencentyun/wafer-solution/wiki/%E4%BF%A1%E9%81%93%E6%9C%8D%E5%8A%A1)小程序支持利用腾讯云的信道资源使用 WebSocket 服务。 ```js // 创建信道，需要给定后台服务地址 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 中的[三木聊天室应用源码](https://github.com/tencentyun/wafer-client-demo/blob/master/pages/chat/chat.js)。 关于信道服务详细技术说明，请参考 [Wiki](https://github.com/tencentyun/wafer-solution/wiki/%E4%BF%A1%E9%81%93%E6%9C%8D%E5%8A%A1)。 ## API ### setLoginUrl 设置会话服务登录地址。 #### 语法 ```js qcloud.setLoginUrl(loginUrl); ``` #### 参数 |参数         |类型 |说明 |-------------|---------------|-------------- |loginUrl |string |会话服务登录地址 ### login 登录，建立微信小程序会话。 #### 语法 ```js qcloud.login(options); ``` #### 参数 |参数         |类型 |说明 |-------------|---------------|-------------- |options     |PlainObject   |会话服务登录地址 |options.success | () => void | 登录成功的回调 |options.error | (error) => void | 登录失败的回调 ### request 进行带会话的请求。 #### 语法 ```js qcloud.request(options); ``` #### 参数 |参数         |类型 |说明 |-------------|---------------|-------------- |options     |PlainObject   | 会话服务登录地址 |options.login | bool         | 是否自动登录以获取会话，默认为 false |options.url   | string       | 必填，要请求的地址 |options.header | PlainObject | 请求头设置，不允许设置 Referer |options.method | string     | 请求的方法，默认为 GET |options.success | (response) => void | 登录成功的回调。 |options.error | (error) => void | 登录失败的回调 |options.complete | () => void | 登录完成后回调，无论成功还是失败 ### Tunnel 表示一个信道。由于小程序的限制，同一时间只能有一个打开的信道。 #### constructor ##### 语法 ```js var tunnel = new Tunnel(tunnelUrl); ``` #### 参数 |参数         |类型 |说明 |-------------|---------------|-------------- |tunnelUrl   |String   | 会话服务登录地址 #### on 监听信道上的事件。信道上事件包括系统事件和服务器推送消息。 ##### 语法 ```js tunnel.on(type, listener); ``` ##### 参数 |参数         |类型 |说明 |-------------|---------------|-------------- |type       |string     | 监听的事件类型 |listener     |(message?: any) => void | 监听器，具体类型的事件发生时调用监听器。如果是消息，则会有消息内容。 ##### 事件 |事件 |说明 |-------------|------------------------------- |connect |信道连接成功后回调 |close |信道关闭后回调 |reconnecting |信道发生重连时回调 |reconnected |信道重连成功后回调 |error |信道发生错误后回调 |[message]   |信道服务器推送过来的消息类型，如果消息类型和上面内置的时间类型冲突，需要在监听的时候在消息类型前加 `@` |\*           |监听所有事件和消息，监听器第一个参数接收到时间或消息类型  #### open 打开信道，建立连接。由于小程序的限制，同一时间只能有一个打开的信道。 ##### 语法 ```js tunnel.open(); ``` #### emit 向信道推送消息。 ##### 语法 ```js tunnel.emit(type, content); ``` ##### 参数 |参数         |类型 |说明 |-------------|---------------|-------------- |type       |string       | 要推送的消息的类型 |content |any | 要推送的消息的内容 #### close 关闭信道 ##### 语法 ```js tunnel.close(); ``` ## LICENSE [MIT](LICENSE)