云端与局域网接入

选择通信通道

跨网络屏幕使用项目云端服务，同网中控可选择局域网直连；两种通道共用命令 data。云端地址、产品标识和凭据随项目交付提供；本站另列的设备 API 属于独立接入体系。

消息携带八位 mid 与毫秒时间戳 ts，应答保留原 mid。用它关联请求、应答和异步事件，不应把命令确认等同于实体屏幕已经显示。

{"device":123,"mid":"ab12cd34","data":{"screen":{"action":"list"}},"ts":1793664000000}

连接局域网设备

播放器从 9756 端口开始尝试，被占用时顺延最多九个端口；GET /ping 返回实际端口。优先使用 WebSocket /order，POST /order 为旧版兼容通道。局域网令牌是设备的六位控制码，空值或禁用状态会拒绝控制码访问。

• 原生客户端可使用 X-SS-Token、X-SS-Remote-Id 和 X-SS-Remote-Name 请求头。控制码应保密，局域网监听端口不应直接暴露到公网。
• HTTPS 网页不能默认直接访问不加密的 HTTP/WS 局域网端点，浏览器会受到混合内容限制。使用交付的应用或适当的本地服务。局域网 system 命令仅支持 info 和 reg。

GET http://<device-ip>:<port>/ping
ws://<device-ip>:<port>/order?token=<control-code>&rid=<remote-id>&rname=<remote-name>

{"mid":"ab12cd34","data":{"screen":{"action":"list"}},"ts":1793664000000}

应答与错误

成功操作返回 ret: ok，查询可能直接返回数据。失败返回 ret: error 与 msg。常见错误包括 invalid param、invalid state、unsupported、queue full 和 device is in remote mode。结果不明时先查询设备状态，再决定是否重试。

{"mid":"ab12cd34","ret":"ok"}
{"mid":"ab12cd34","ret":"error","msg":"unsupported"}