小程序/小玩法/直播互动工具使用云托管webSocket
介绍
开发者可在小程序,小玩法,直播互动工具里面使用相关webSocket API,监听服务端相关推送事件。
操作指引
- 1.通过createCloud 创建客户端云托管实例。
const cloud = tt.createCloud({ envID: 'env-0WIYiY4PNP' });
- 2.通过connectContainer 创建 webSocket 连接实例,必须传入开发者服务接口地址。
const webSocket = cloud.connectContainer({ path: "/path" });
- 3.通过 webSocket 实例来监听服务端推送的数据或者向服务端推送数据。
webSocket.onMessage((message) => { // 每次 WebSocket 发送的信息 console.log("socket message:", message); });
注意事项
最多可以同时存在 5 个 WebSocket 连接。connectContainer 返回成功只代表连接任务创建成功,真正连接服务器成功需要监听onOpen回调。退后台5s后websocket会自动断连。
tt.createCloud
基础库 2.70.0 开始支持本方法,这是一个同步方法
返回一个Cloud云调用实例
语法
tt.createCloud(options)
参数说明
options 为object类型,属性如下:
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
envID | string | - | 是 | 云环境ID | 小程序最低基础库版本为2.70.0 直播互动工具最低基础库版本为3.48.0.0 |
serviceID | string | - | 否 | 云服务ID | 小程序最低基础库版本为2.70.0 直播互动工具最低基础库版本为3.48.0.0 |
返回值
Cloud实例
Cloud
通过
tt.createCloud
获取的实例,通过它访问云托管服务。方法
方法名 | 最低支持版本 |
callContainer | 小程序最低基础库版本为2.70.0 直播互动工具最低基础库版本为3.48.0.0 |
CloudID | 小程序最低基础库版本为2.70.0 直播互动工具最低基础库版本为3.48.0.0 |
uploadFile | 小程序最低基础库版本为2.76.0 |
downLoadFile | 小程序最低基础库版本为2.76.0 |
deleteFile | 小程序最低基础库版本为2.76.0 |
getTempFileURL | 小程序最低基础库版本为2.76.0 |
connectContainer | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
Cloud.connectContainer
小程序基础库2.78.0开始支持本方法,直播互动工具最低基础库版本为3.48.0.0,这是一个异步方法
创建一个 抖音云托管的WebSocket 连接实例,并通过返回的 CloudSocketTask 操作该连接。
语法
Cloud.connectContainer(options);
参数说明
options 为 object 类型,属性如下:
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
path | string | | 是 | 开发者服务接口地址 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
serviceID | string | | 否 | 云服务id。若不传以tt.createCloud传入的服务id为准,至少需要一个有效serviceID | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
header | object | | 否 | HTTP Header | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
success | function | | 否 | 接口调用成功后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
fail | function | | 否 | 接口调用失败后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
complete | function | | 否 | 接口调用结束后的回调函数(调用成功、失败都会执行) | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
回调成功
属性名 | 类型 | 说明 | 最低支持版本 |
errMsg | string | "connectContainer:ok" | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
socketTaskId | number | 任务id | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
回调失败
参数为 Object 类型,属性如下:
属性名 | 类型 | 说明 | 最低支持版本 |
errMsg | string | "connectContainer:fail " + 详细错误信息 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
errNo | number | 错误码 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
返回值
CloudSocketTask实例
CloudSocketTask
基础库2.78.0开始支持本类型实例
通过
Cloud.connectContainer
获取的 WebSocket 任务实例属性
只读属性
属性 | 类型/常量 | 说明 | 最低支持版本 |
readyState | number | undefined | 表示 Socket 连接状态 code; 若由于参数错误导致未创建连接, 则为 undefined | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
CloudSocketTask.CONNECTING | 0 | 表示 Socket 正在连接 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
CloudSocketTask.OPEN | 1 | 表示 Socket 连接已经打开 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
CloudSocketTask.CLOSING | 2 | 表示 Socket 连接关闭中 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
CloudSocketTask.CLOSED | 3 | 表示 Socket 连接已关闭 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
方法
方法名 | 说明 | 最低支持版本 |
send | 通过 WebSocket 连接发送数据 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
close | 关闭 WebSocket 连接 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
onOpen | 监听 WebSocket 连接服务器成功的事件 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
onClose | 监听 WebSocket 与服务器的连接断开的事件 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
onMessage | 监听 WebSocket 接收到服务器发送信息的事件 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
onError | 监听 WebSocket 发生错误的事件 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
getExtensionManager | 获取扩展接口管理器 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
CloudSocketTask.send
基础库2.78.0开始支持本方法,这是一个异步方法
通过 WebSocket 连接向服务端发送数据
语法
CloudSocketTask.send(options);
参数说明
options 为 object 类型,属性如下:
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
data | string/arraybuffer | | 是 | 数据内容 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
success | function | | 否 | 接口调用成功后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
fail | function | | 否 | 接口调用失败后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
complete | function | | 否 | 接口调用结束后的回调函数(调用成功、失败都会执行) | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
回调成功
属性名 | 类型 | 说明 | 最低支持版本 |
errMsg | string | "CloudSocketTask.send:ok" | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
回调失败
属性名 | 类型 | 说明 | 最低支持版本 |
errMsg | string | "CloudSocketTask.send:fail " + 详细错误信息 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
errNo | number | 错误码 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
返回值
无
CloudSocketTask.close
基础库2.78.0开始支持本方法,这是一个异步方法
关闭 WebSocket 连接
语法
CloudSocketTask.close(options);
参数说明
options 为 object 类型,属性如下:
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
code | number | 1000 | 否 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 | |
reason | string | normal close | 否 | 连接被关闭的原因 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
success | function | | 否 | 接口调用成功后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
fail | function | | 否 | 接口调用失败后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
complete | function | | 否 | 接口调用结束后的回调函数(调用成功、失败都会执行) | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
回调成功
属性名 | 类型 | 说明 | 最低支持版本 |
errMsg | string | "CloudSocketTask.close:ok" | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
回调失败
属性名 | 类型 | 说明 | 最低支持版本 |
errMsg | string | "CloudSocketTask.close:fail " + 详细错误信息 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
errNo | number | 错误码 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
返回值
无
CloudSocketTask.onOpen
基础库2.78.0开始支持本方法,这是一个同步方法
监听 WebSocket 连接服务器成功的事件。表示 WebSocket 的状态变成 open,可以发送数据给服务器。
语法
CloudSocketTask.onOpen(callback);
参数说明
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
callback | function | | 是 | 连接成功的事件回调 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
callback回调函数参数说明
参数为 Object 类型,属性如下:
属性名 | 类型 | 说明 | 最低支持版本 |
header | object | 连接服务器返回的 Response Header | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
返回值
无
CloudSocketTask.onClose
基础库2.78.0开始支持本方法,这是一个同步方法
监听 WebSocket 与服务器连接断开的事件。
语法
CloudSocketTask.onClose(callback);
参数说明
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
callback | function | | 是 | 连接断开的事件回调 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
callback回调函数参数说明
参数为 Object 类型,属性如下:
属性名 | 类型 | 说明 | 最低支持版本 |
reason | string | 关闭原因,正常情况与CloudSocketTask.close传的相同 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
code | number | 关闭连接状态码,正常情况与CloudSocketTask.close传的相同 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
code保留值
值 | 说明 |
1000 | 正常关闭 |
1001 | 处于后台等原因导致的关闭 |
1006 | 断网、飞行模式、其他客户端网络异常 |
返回值
无
CloudSocketTask.onMessage
基础库2.78.0开始支持本方法,这是一个同步方法
监听 WebSocket 接收到服务器发送信息的事件。
语法
CloudSocketTask.onMessage(callback);
参数说明
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
callback | function | | 是 | 接收到服务器发送信息的事件回调 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
callback回调函数参数说明
参数为 Object 类型,属性如下:
属性名 | 类型 | 说明 | 最低支持版本 |
data | string/arraybuffer | 数据内容 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
返回值
无
CloudSocketTask.onError
基础库2.78.0开始支持本方法,这是一个同步方法
监听 WebSocket 发生错误的事件。
语法
CloudSocketTask.onError(callback);
参数说明
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
callback | function | | 是 | 连接发生错误的事件回调 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
callback回调函数参数说明
参数为 Object 类型,属性如下:
属性名 | 类型 | 说明 | 最低支持版本 |
errMsg | string | 错误信息 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
返回值
无
CloudSocketTask.getCloudExtensionManager
基础库2.78.0开始支持本方法,这是一个同步方法
获取WebSocket 实例的扩展能力器。
语法
CloudSocketTask.getCloudExtensionManager()
返回
CloudExtensionManager实例
CloudExtensionManager
基础库2.78.0开始支持本类型实例
方法
方法 | 说明 | 最低支持版本 |
changeGroup | 切换WebSocket组播数据组 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
CloudExtensionManager.joinGroup
基础库2.78.0开始支持本方法,这是一个异步方法
加入WebSocket组播数据组
语法
CloudExtensionManager.joinGroup(options)
参数说明
options 为 object 类型,属性如下:
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
groupInfoArray | GroupInfo[] | | 是 | 组播数据组信息,数组最长为5 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
success | function | | 否 | 接口调用成功后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
fail | function | | 否 | 接口调用失败后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
complete | function | | 否 | 接口调用结束后的回调函数(调用成功、失败都会执行) | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
GroupInfo
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
groupName | string | | 是 | 数据组名称 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
groupValue | string | | 是 | 数据组内容 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
回调成功
属性名 | 类型 | 说明 |
errMsg | string | "CloudExtensionManager.joinGroup:ok" |
result | JoinResult[] | 入组结果 |
JoinResult
参数 | 类型 | 说明 | 最低支持版本 |
groupName | string | 数据组名称 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
groupValue | string | 数据组内容 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
status | number | 入组结果 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
- •入组结果
status | 说明 |
0 | 入组成功 |
10000 | 组不存在 |
回调失败
属性名 | 类型 | 说明 |
errMsg | string | "CloudExtensionManager.joinGroup:fail " + 详细错误信息 |
errNo | number | 错误码 |
返回值
无
CloudExtensionManager.exitGroup
基础库2.78.0开始支持本方法,这是一个异步方法
退出WebSocket组播数据组
语法
CloudExtensionManager.exitGroup(options)
参数说明
options 为 object 类型,属性如下:
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
groupInfoArray | GroupInfo[] | | 是 | 组播数据组信息,数组最长为5 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
success | function | | 否 | 接口调用成功后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
fail | function | | 否 | 接口调用失败后的回调函数 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
complete | function | | 否 | 接口调用结束后的回调函数(调用成功、失败都会执行) | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
GroupInfo
参数 | 类型 | 默认值 | 必填 | 说明 | 最低支持版本 |
groupName | string | | 是 | 数据组名称 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
groupValue | string | | 是 | 数据组内容 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
回调成功
属性名 | 类型 | 说明 |
errMsg | string | "CloudExtensionManager.exitGroup:ok" |
result | ExitResult[] | 退组结果 |
ExitResult
参数 | 类型 | 说明 | 最低支持版本 |
groupName | string | 数据组名称 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
groupValue | string | 数据组内容 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
status | number | 退组结果 | 小程序最低基础库版本为2.78.0 直播互动工具最低基础库版本为3.48.0.0 |
- •入组结果
status | 说明 |
0 | 退组成功 |
10000 | 组不存在 |
回调失败
属性名 | 类型 | 说明 |
errMsg | string | "CloudExtensionManager.exitGroup:fail " + 详细错误信息 |
errNo | number | 错误码 |
返回
无
代码示例
<!-- index.ttml --> <view> <button size="default" bindtap="socketConnect">创建 WebSocket </button> <button size="default" bindtap="closeSocket"> 关闭 WebSocket </button> <input value="{{inputValue}}" bindinput="inputChange"></input> <button size="default" bindtap="sendSocket"> 发送 WebSocket 数据 </button> <button size="default" bindtap="joinGroup"> 加入组播数据组 </button> <button size="default" bindtap="exitGroup"> 离开组播数据组 </button> <view>
// index.js let cloudSocketTask; let cloud; Page({ data: { inputValue: "", isOpen:false, }, onLoad(){ cloud = tt.createCloud({envID:'envID',serviceID:'serviceID'}) }, socketConnect() { // 如果已经创建,就不再创建了 if (cloudSocketTask) { return; } cloudSocketTask = cloud.connectContainer({ path: "path", //开发者提供的url success: (res) => { // 创建成功的回调 console.log("创建成功", res); }, fail: (res) => { // 创建失败的回调 console.log("创建失败", res); }, complete: (res) => { // 创建完毕的回调 console.log("创建完毕", res); }, }); cloudSocketTask.onOpen(() => { // 此时表示 websocket 已经处于 open 状态 console.log("WebSocket 已连接"); this.setData({ isOpen:true }) }); cloudSocketTask.onClose(() => { // 此时表示 websocket 已经处于 closed 状态 console.log("WebSocket 已断开"); this.setData({ isOpen:false }) }); cloudSocketTask.onError((error) => { // 此处表示 websocket 有错误发生 console.error("WebSocket 发生错误:", error); }); cloudSocketTask.onMessage((message) => { // 每次 WebSocket 发送的信息 console.log("socket message:", message); }); }, closeSocket() { // 主动关闭 websocket 连接 console.log("---- close"); if (cloudSocketTask) { cloudSocketTask.close({ success: (res) => { // 关闭成功的回调 console.log("close success", res); }, fail: (res) => { // 关闭失败的回调 console.log("close fail", res); }, }); } }, sendSocket() { // 向 websocket 发送信息 console.log("---- send", this.data.inputValue); if (this.data.isOpen) { cloudSocketTask.send({ data: this.data.inputValue, success: (res) => { // 发送成功的回调 console.log("send success", res); }, fail: (res) => { // 发送失败的回调 console.log("send fail", res); }, }); } }, joinGroup(){ // 切换组播数据组 console.log("---- joinGroup"); if (cloudSocketTask) { const extensionManager = cloudSocketTask.getCloudExtensionManager() extensionManger.joinGroup({ groupInfoArray:[{ groupName:"group1", groupValue:"tag1" }], success: (res) => { // 加入组播组成功的回调 console.log("join group success", res); }, fail: (res) => { // 加入组播组失败的回调 console.log("join group fail", res); }, }); } }, exitGroup(){ // 切换组播数据组 console.log("---- exitGroup"); if (cloudSocketTask) { const extensionManager = cloudSocketTask.getCloudExtensionManager() extensionManger.exitGroup({ groupInfoArray:[{ groupName:"group1", groupValue:"tag1" }], success: (res) => { // 离开组播组成功的回调 console.log("exit group success", res); }, fail: (res) => { // 离开组播组失败的回调 console.log("exit group fail", res); }, }); } }, inputChange(e) { this.setData({ inputValue: e.detail.value, }); }, });