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

    收藏
    我的收藏

    介绍

    在很多业务场景下,开发者无法通过抖音端内或者抖音云提供的SDK来使用抖音云websocket能力;针对这种场景,抖音云提供了自定义域名的能力,开发者可以使用自行持有的域名在抖音云控制台上完成绑定,绑定完成后就基于该域名来向抖音云发起websocket请求。

    使用限制

    目前通过自定义域名使用抖音云websocket能力还处在白名单中,您可以通过填写工单 来申请(在申请使用的能力一栏中选择“自定义域名支持websocket”);我们会在3个工作日内进行审批。

    操作指南

    绑定自定义域名

      1.开发者首先在抖音云控制台上绑定自定义域名,具体可以参考:绑定自定义域名;
      2.若开发者没有自己的域名,可以通过抖音云提供的默认公网域名来进行接入测试,在抖音云控制台点击【服务】-【访问控制】,打开域名访问开关可以得到默认公网域名:
      3.如果想通过自定义域名的方式访问到后端服务,还需要添加对应的path授权外网访问,具体可以参考:添加访问路径;

    获取websocket连接ID

    开发者在建连或者进组/退组时均需要携带websocket连接ID,用于权限校验;否则无法建连成功;具体获取的方式可以参考:生成websocket连接id。
    关于websocket连接ID的说明:
      •抖音云网关在websocket建连时会基于该连接ID进行身份验证,单个连接ID仅允许建立一次websocket连接,无法复用;客户端在建立新的websocket连接时需要获取新的连接ID。

    websocket建连

    开发者可以通过如下websocket地址请求抖音云网关进行建连:
    ws(s)://{host}/__dycloud__/ws/connect/
    其中:
      •ws(s)表示若开发者绑定自定义域名时勾选了HTTPS协议,则可以通过WSS协议进行websocket建连;
      •{host}表示开发者持有的域名,或者对应服务默认公网域名;
      •/__dycloud__/ws/connect/代表抖音云网关的websocket建连path,注意这里是两个短下横线_;
    除此之外,开发者还需要在websocket建连时携带如下请求头信息:
    key
    value(string)
    作用
    X-TT-WS-CONN-ID
    4392960514
    必传,websocket单次连接ID,用于权限校验
    X-TT-SERVICE-PATH
    /web_scoket/on_connect
    必传,抖音云网关将根据此路径通过HTTP回调的方式通知开发者服务,具体参考:websocket建连回调通知
    客户端示例(Golang):
    package main import ( "fmt" "github.com/gorilla/websocket" "io" "log" "net/http" "net/url" ) func main() { host := "${your_addr}" // 这里替换成自定义域名/默认公网域名的host u := url.URL{Scheme: "wss", Host: addr, Path: "/__dycloud__/ws/connect/"} header := http.Header{} header.Set("X-TT-WS-CONN-ID", "") // 这里输入对应的连接id header.Set("X-TT-SERVICE-PATH", "") // 这里输入对应的后端回调地址 // 发起websocket建连 c, resp, err := websocket.DefaultDialer.Dial(u.String(), header) if err != nil { log.Fatal("websocket connect fail, err: ", err) } // 业务逻辑处理... }

    websocket进组/换组

    组推是一种比较常见的场景,比如将一条消息推送给直播间内的所有在线观众;开发者的客户端同样可以基于自定义域名,通过HTTP协议访问抖音云网关,来实现组推的能力:
    进组:http(s)://{host}/__dycloud__/ws/join_group/ 退组:http(s)://{host}/__dycloud__/ws/exit_group/
    其中:
      •http(s)表示若开发者绑定自定义域名时勾选了HTTPS协议,则可以通过https访问。
      •{host}表示开发者自己的域名,或者对应服务默认公网域名;
      •/__dycloud__/ws/join_group/或者__dycloud__/ws/exit_group表示进组以及退组的path;注意这里是两个短下横线_;
    除此之外,开发者还需要在websocket建连时携带如下请求头信息:
    key
    value(string)
    作用
    X-TT-WS-CONN-ID
    4392960514
    必传,websocket单次连接ID,用于权限校验
    X-TT-WS-GROUPNAME
    live-room
    必传,表示组名
    X-TT-WS-GROUPVALUE
    live-room-id-1
    必传,表示组名对应的组值
    请求示例:
    curl --location --request POST 'https://host/__dycloud__/ws/join_group/' \ --header 'Content-Type: application/json' \ --header 'X-TT-WS-CONN_ID: 4392960514' \ --header 'X-TT-WS-GROUPNAME: live-room' \ --header 'X-TT-WS-GROUPVALUE: live-room-id-1'

    常见问题

    建连请求失败,如何排查?

    websocket协议是基于HTTP协议的一种全双工通信,websocket建连失败时,可以根据HTTP响应的请求头来判断请求失败的原因,具体如下:
    HTTP响应请求头
    含义
    StatusCode
    HTTP协议的通用状态返回码
    X-Status-Code
    websocket建连的状态码,配合StatusCode判断失败的原因:
      •StatusCode = 401,X-Status-Code = 10030:请求携带的X-TT-WS-CONN-ID不合法,请检查该参数是否正确传递;
      •StatusCode = 500,X-Status-Code = 11020:连接注册失败,请重试;
      •StatusCode = 500,X-Status-Code = 11030:通知开发者服务失败,请检查对应的后端服务是否正确监听在对应的X-TT-SERVICE-PATH上;
      •StatusCode = 500,X-Status-Code = 11040:协议升级失败,请检查客户端的请求是否符合websocket协议;
    X-Tt-LogId
    请求的全局LogId,若未能排查出对应问题,可以通过该参数提交工单或者在对应技术支持群中询问对应技术人员。
    ​
    ​