小程序/小玩法/直播互动工具使用云托管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
关闭连接状态码,需符合RFC标准,保留字段会兼容成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, }); }, });