WebRTC开发者平台

📱 设备如何关联

设备通过自动注册API使用您的app_id和app_secret进行注册后，会自动关联到您的账户，无需手动绑定。

POST /api/v3/devices/auto-register
{
  "app_id": "YOUR_APP_ID",
  "app_secret": "YOUR_APP_SECRET",
  "device_serial": "DEVICE_SN_123",
  "device_name": "我的设备"
}

详细的统计图表功能正在开发中...

📡 配置说明

STUN/TURN服务器是WebRTC建立P2P连接的关键组件：

• STUN服务器：用于NAT穿透，帮助设备发现自己的公网IP和端口
• TURN服务器：当P2P连接失败时，作为中继服务器转发数据
• 设备在调用 auto-register API时会自动获取这些配置
• 您可以使用公共STUN服务器，或部署私有的STUN/TURN服务器

配置一个或多个STUN服务器（每行一个），建议配置多个以提高连接成功率。

TURN服务器用于P2P连接失败时的数据中继，需要认证。如果没有TURN服务器可留空。

测试配置的STUN/TURN服务器是否可用，确保设备能够正常建立WebRTC连接。

保存后，设备在注册时将自动获取最新配置

🚀 快速开始

设备接入流程：

1. 使用 app_id 和 app_secret 进行设备自动注册
2. 获取设备专属的 device_token
3. 使用 device_token 建立 WebSocket连接
4. 发送 设备上线 消息
5. 接收和处理 信令消息（呼叫、挂断等）
6. 定期发送 心跳 保持连接
7. Token过期前自动 刷新

您的凭证：

app_id: YOUR_APP_ID
app_secret: YOUR_APP_SECRET

设备首次启动或重启时，使用您的 app_id 和 app_secret 进行自动注册，获取设备Token：

POST http://114.132.181.107:8080/api/v3/devices/auto-register
Content-Type: application/json

{
  "app_id": "YOUR_APP_ID",
  "app_secret": "YOUR_APP_SECRET",
  "device_serial": "YOUR_DEVICE_SERIAL_NUMBER",  // 设备唯一序列号（必填）
  "device_name": "门口机01",                      // 设备显示名称（选填）
  "device_type": "webrtc_client",                 // 设备类型（选填）
  "manufacturer": "YourCompany",                  // 制造商（选填）
  "model": "Model-A1",                            // 型号（选填）
  "version": "1.0.0"                              // 固件版本（选填）
}

响应示例（成功）：
{
  "code": 2000,
  "message": "设备注册成功",
  "data": {
    "device_id": "DEV1735123456789abc",
    "device_serial": "YOUR_DEVICE_SERIAL_NUMBER",
    "device_name": "门口机01",
    "device_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",  // ⭐ 重要：保存此Token
    "token_type": "Bearer",
    "expires_in": 86400,                           // Token有效期（秒）24小时
    "webrtc_config": {                             // 🆕 WebRTC配置（ICE服务器）
      "ice_servers": [
        {
          "urls": ["stun:114.132.181.107:3478"]   // STUN服务器
        },
        {
          "urls": ["stun:stun.qq.com:3478"]       // 备用STUN服务器
        },
        {
          "urls": ["turn:114.132.181.107:3478"],  // TURN服务器（如果配置了）
          "username": "webrtc",
          "credential": "password"
        }
      ]
    }
  }
}

⚠️ 重要提示：

• device_serial 必须是设备的唯一标识符（如MAC地址、SN码等）
• 首次注册会创建设备记录；后续使用相同 device_serial 注册会更新信息并刷新Token
• Token有效期24小时，过期前需要重新注册或刷新Token
• 建议在设备启动时、网络重连后、Token过期前执行自动注册
• 🆕 WebRTC配置：响应中包含 webrtc_config 字段，包含STUN/TURN服务器列表，设备应使用此配置初始化WebRTC连接

📝 C++示例：使用WebRTC配置初始化连接

在C++端使用libdatachannel库时，应该将服务器返回的ICE配置用于初始化PeerConnection：

// 1. 解析注册响应中的webrtc_config
nlohmann::json registerResponse = parseRegisterResponse();
if (registerResponse.contains("webrtc_config") && 
    registerResponse["webrtc_config"].contains("ice_servers")) {
    
    // 2. 配置WebRTC
    rtc::Configuration config;
    
    // 3. 遍历并添加ICE服务器
    for (auto& server : registerResponse["webrtc_config"]["ice_servers"]) {
        if (server.contains("urls")) {
            // 处理urls数组
            if (server["urls"].is_array()) {
                for (auto& url : server["urls"]) {
                    config.iceServers.push_back(url.get<std::string>());
                }
            } else {
                config.iceServers.push_back(server["urls"].get<std::string>());
            }
        }
    }
    
    // 4. 创建PeerConnection
    auto peerConnection = std::make_shared<rtc::PeerConnection>(config);
    
    std::cout << "✅ 已使用服务器配置初始化WebRTC，ICE服务器数量: " 
              << config.iceServers.size() << std::endl;
} else {
    // 使用默认配置
    rtc::Configuration config;
    config.iceServers.push_back("stun:114.132.181.107:3478");
    config.iceServers.push_back("stun:stun.qq.com:3478");
    auto peerConnection = std::make_shared<rtc::PeerConnection>(config);
}

为保持设备长期在线，需要在Token过期前刷新。推荐两种方式：

方式一：重新执行自动注册（推荐）

直接重新调用 auto-register API，使用相同的 device_serial，会返回新的Token。

// 在Token过期前1小时刷新（建议）
if (当前时间 >= Token获取时间 + 23小时) {
    // 重新调用auto-register获取新Token
    newToken = auto_register(...);
    // 断开旧WebSocket连接
    ws.close();
    // 使用新Token重新建立WebSocket连接
    ws = new WebSocket('ws://...?token=' + newToken);
}

方式二：使用刷新Token API

POST http://114.132.181.107:8080/api/v3/developers/refresh-token
Authorization: Bearer YOUR_OLD_TOKEN

响应示例：
{
  "code": 2000,
  "message": "Token刷新成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400
  }
}

💡 最佳实践：

• 在设备启动后立即记录Token获取时间
• 设置定时器，在Token过期前1小时自动刷新
• 如果刷新失败，回退到重新注册
• WebSocket连接断开时，使用新Token重连

使用获取的 device_token 建立WebSocket连接：

WebSocket URL:
ws://114.132.181.107:8080/ws?token=YOUR_DEVICE_TOKEN

C++ 示例（使用libwebsockets）：
// 1. 设置连接参数
std::string ws_url = "ws://114.132.181.107:8080/ws?token=" + device_token;

// 2. 建立连接
websocket_client->connect(ws_url);

// 3. 连接成功回调
void on_open() {
    std::cout << "WebSocket连接成功" << std::endl;
    // 发送设备上线消息（见步骤4）
    send_device_online();
}

// 4. 接收消息回调
void on_message(const std::string& message) {
    // 解析JSON-RPC消息（见步骤5）
    handle_signaling_message(message);
}

// 5. 连接断开回调
void on_close() {
    std::cout << "WebSocket连接断开，准备重连..." << std::endl;
    // 实现指数退避重连
    reconnect_with_backoff();
}

🔄 重连策略：

int reconnect_delay = 1;  // 初始1秒
const int max_delay = 60;  // 最大60秒

void reconnect_with_backoff() {
    sleep(reconnect_delay);
    if (!connect()) {
        reconnect_delay = std::min(reconnect_delay * 2, max_delay);
        reconnect_with_backoff();
    } else {
        reconnect_delay = 1;  // 重置延迟
    }
}

WebSocket连接成功后，立即发送设备上线消息，通知服务器设备已就绪：

消息格式（JSON-RPC 2.0）：
{
  "jsonrpc": "2.0",
  "id": "device_online_1735123456789",
  "method": "device_online",
  "params": {
    "device_id": "YOUR_DEVICE_SERIAL",
    "device_name": "门口机01",
    "status": "online",
    "timestamp": 1735123456789
  }
}

服务器响应：
{
  "jsonrpc": "2.0",
  "id": "device_online_1735123456789",
  "result": {
    "status": "success",
    "message": "设备上线成功"
  }
}

C++ 示例：

void send_device_online() {
    json message = {
        {"jsonrpc", "2.0"},
        {"id", "device_online_" + std::to_string(get_timestamp())},
        {"method", "device_online"},
        {"params", {
            {"device_id", device_serial},
            {"device_name", device_name},
            {"status", "online"},
            {"timestamp", get_timestamp()}
        }}
    };
    
    websocket_send(message.dump());
}

所有信令消息采用 JSON-RPC 2.0 格式。以下是常用的信令消息类型：

📋 获取在线设备列表

发送：
{
  "jsonrpc": "2.0",
  "id": "device_list_req_001",
  "method": "device_list_request",
  "params": {}
}

接收：
{
  "jsonrpc": "2.0",
  "id": "device_list_req_001",
  "result": {
    "method": "device_list_result",
    "devices": [
      {
        "device_id": "W7711581223",
        "device_name": "门口机01",
        "device_status": "online",
        "room_id": ""
      },
      {
        "device_id": "WebWebRTC_ABC",
        "device_name": "Web客户端",
        "device_status": "online",
        "room_id": ""
      }
    ]
  }
}

📞 发起呼叫（主叫）

发送呼叫请求：
{
  "jsonrpc": "2.0",
  "id": "call_request_001",
  "method": "call",
  "params": {
    "caller_id": "YOUR_DEVICE_SERIAL",
    "callee_id": "TARGET_DEVICE_SERIAL",
    "room_id": "room_1735123456789",  // 房间ID（可选，服务器会生成）
    "timestamp": 1735123456789
  }
}

接收对方应答：
{
  "jsonrpc": "2.0",
  "method": "call_accepted",
  "params": {
    "caller_id": "YOUR_DEVICE_SERIAL",
    "callee_id": "TARGET_DEVICE_SERIAL",
    "room_id": "room_1735123456789"
  }
}

开始WebRTC协商（发送offer）：
{
  "jsonrpc": "2.0",
  "method": "offer",
  "params": {
    "from": "YOUR_DEVICE_SERIAL",
    "to": "TARGET_DEVICE_SERIAL",
    "room_id": "room_1735123456789",
    "sdp": "v=0\r\no=- 123456789 2 IN IP4 127.0.0.1\r\n..."
  }
}

📲 接收呼叫（被叫）

接收来电通知：
{
  "jsonrpc": "2.0",
  "method": "incoming_call",
  "params": {
    "caller_id": "CALLER_DEVICE_SERIAL",
    "callee_id": "YOUR_DEVICE_SERIAL",
    "room_id": "room_1735123456789",
    "caller_name": "门口机01",
    "timestamp": 1735123456789
  }
}

自动接听：
{
  "jsonrpc": "2.0",
  "id": "answer_001",
  "method": "answer",
  "params": {
    "caller_id": "CALLER_DEVICE_SERIAL",
    "callee_id": "YOUR_DEVICE_SERIAL",
    "room_id": "room_1735123456789"
  }
}

接收WebRTC offer并返回answer：
// 1. 接收offer
{
  "jsonrpc": "2.0",
  "method": "offer",
  "params": {
    "from": "CALLER_DEVICE_SERIAL",
    "to": "YOUR_DEVICE_SERIAL",
    "room_id": "room_1735123456789",
    "sdp": "v=0\r\n..."
  }
}

// 2. 创建answer并发送
{
  "jsonrpc": "2.0",
  "method": "answer",
  "params": {
    "from": "YOUR_DEVICE_SERIAL",
    "to": "CALLER_DEVICE_SERIAL",
    "room_id": "room_1735123456789",
    "sdp": "v=0\r\n..."
  }
}

📡 ICE候选交换

发送ICE候选：
{
  "jsonrpc": "2.0",
  "method": "ice_candidate",
  "params": {
    "from": "YOUR_DEVICE_SERIAL",
    "to": "TARGET_DEVICE_SERIAL",
    "room_id": "room_1735123456789",
    "candidate": {
      "candidate": "candidate:1 1 udp 2122194687 192.168.1.100 54321 typ host",
      "sdpMid": "0",
      "sdpMLineIndex": 0
    }
  }
}

接收对方ICE候选：
{
  "jsonrpc": "2.0",
  "method": "ice_candidate",
  "params": {
    "from": "TARGET_DEVICE_SERIAL",
    "to": "YOUR_DEVICE_SERIAL",
    "room_id": "room_1735123456789",
    "candidate": { ... }
  }
}

📴 挂断呼叫

主动挂断：
{
  "jsonrpc": "2.0",
  "id": "hangup_001",
  "method": "hangup",
  "params": {
    "caller_id": "YOUR_DEVICE_SERIAL",
    "callee_id": "TARGET_DEVICE_SERIAL",
    "room_id": "room_1735123456789",
    "reason": "user_hangup"
  }
}

接收对方挂断：
{
  "jsonrpc": "2.0",
  "method": "hangup",
  "params": {
    "caller_id": "TARGET_DEVICE_SERIAL",
    "callee_id": "YOUR_DEVICE_SERIAL",
    "room_id": "room_1735123456789",
    "reason": "user_hangup"
  }
}

💓 心跳保活

每30秒发送心跳：
{
  "jsonrpc": "2.0",
  "id": "ping_1735123456789",
  "method": "ping",
  "params": {
    "device_id": "YOUR_DEVICE_SERIAL",
    "timestamp": 1735123456789
  }
}

服务器响应：
{
  "jsonrpc": "2.0",
  "id": "ping_1735123456789",
  "result": {
    "method": "pong",
    "timestamp": 1735123456790
  }
}

以下是一个完整的设备间呼叫流程（设备A呼叫设备B）：

1. 设备A：获取在线设备列表
   A → Server: {"method": "device_list_request"}
   Server → A: {"method": "device_list_result", "devices": [...]}

2. 设备A：发起呼叫
   A → Server: {"method": "call", "params": {"caller_id": "A", "callee_id": "B"}}
   Server → B: {"method": "incoming_call", "params": {"caller_id": "A", "callee_id": "B"}}

3. 设备B：自动接听
   B → Server: {"method": "answer", "params": {"caller_id": "A", "callee_id": "B"}}
   Server → A: {"method": "call_accepted", "params": {"caller_id": "A", "callee_id": "B"}}

4. 设备A：创建WebRTC连接并发送offer
   A创建RTCPeerConnection，生成offer SDP
   A → Server: {"method": "offer", "params": {"from": "A", "to": "B", "sdp": "..."}}
   Server → B: {"method": "offer", "params": {"from": "A", "to": "B", "sdp": "..."}}

5. 设备B：接收offer并发送answer
   B设置remote SDP，创建answer SDP
   B → Server: {"method": "answer", "params": {"from": "B", "to": "A", "sdp": "..."}}
   Server → A: {"method": "answer", "params": {"from": "B", "to": "A", "sdp": "..."}}

6. ICE候选交换（双向）
   A → Server: {"method": "ice_candidate", "params": {"from": "A", "to": "B", "candidate": {...}}}
   Server → B: {"method": "ice_candidate", ...}
   B → Server: {"method": "ice_candidate", "params": {"from": "B", "to": "A", "candidate": {...}}}
   Server → A: {"method": "ice_candidate", ...}

7. WebRTC连接建立，音视频流开始传输
   （此时数据通过P2P直接传输，不再经过信令服务器）

8. 通话结束，任意一方发送挂断
   A → Server: {"method": "hangup", "params": {"caller_id": "A", "callee_id": "B"}}
   Server → B: {"method": "hangup", "params": {"caller_id": "A", "callee_id": "B"}}
   双方关闭RTCPeerConnection，清理资源

HTTP API 错误码

• Swagger API文档（交互式）
• WebRTC测试页面
• GitHub代码仓库