# SDK 与示例

*浏览器 JS 参考、服务端签发示例、设备端示例*

## 服务端：签发客户端 Token

后端用工作空间 API Key 调 `POST /api/v1/clients/{id}/token`（或 `/api/v1/clients/ephemeral`）拿到**客户端 Token**，下发给客户端连接。**绝不把 API Key 下发到设备。**

```bash
BASE=https://hearo.apps.aisp24.com   # 本部署的 API 基址
curl -X POST $BASE/api/v1/clients/<id>/token \
  -H "Authorization: Bearer $HEARO_API_KEY" -H "Content-Type: application/json" \
  -d '{"ttlSeconds":3600}'
# -> { "token": "<CLIENT_TOKEN>", "clientId": "...", "expiresAt": "..." }
```

> ℹ️ **任意语言**：签发只是一次 HTTP 调用，任何语言都能用（见 [REST API](/docs/rest-api)）。客户端 Token 是标准 HS256 JWT（`iss=workspaceId`、`sub=clientId`、`aud=hearo-client`），由工作空间的隐藏签名密钥签发——服务端无需自己签，调接口即可。

## 浏览器 JS（参考实现）

控制台「演示」页（Playground）就是一份完整可读的浏览器客户端：getUserMedia 采集、重采样到 16k、分帧发送、下行音频播放、打断处理、默认 WebSocket 与 WebRTC（实验）两条路径。最小骨架见 [快速开始](/docs/quickstart)。

## 设备端示例

`examples/device-client` 是一个命令行设备客户端示例，演示如何用客户端 Token 连接 gateway、推送音频帧、接收事件与音频——适合 IoT / 嵌入式接入参考。

```bash
# 仓库内
cd examples/device-client && go run . --help
```

> 💡 **集成路线**：服务端用 REST 签客户端 Token → 客户端用默认的 [WebSocket](/docs/websocket)、[WebRTC（实验）](/docs/webrtc) 或 [MQTT](/docs/mqtt) 连接（房间由 client→room 映射决定）→ 控制面 [邀请 AI](/docs/agents) 进房间，或给房间配默认智能体（[房间与分组](/docs/rooms)）。