抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 快速入门
  • 开发指南
  • 功能服务
  • 云服务
  • 数据库
  • 对象存储
  • 调用服务
  • 云调用
  • WebSocket
  • 服务端使用云托管 WebSocket
  • 小程序/小玩法/直播互动工具使用云托管webSocket
  • 通过自定义域名使用抖音云websocket能力
  • 配置中心
  • 触发器
  • 监控告警
  • 资源复用
  • 成员管理
  • 费用中心
  • 火山引擎
  • 设置
  • 操作限制
  • 行业解决方案
  • 迁移指南
  • API 参考
  • 最佳实践
  • 产品计费
  • 常见问题
  • 产品动态
  • 小程序/小玩法/直播互动工具使用云托管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, }); }, });
    ​
    ​