开始使用
Orbit 账户的组织方式、控制台各处的功能,以及从登录到让我们的网络开始应答一个域名的最短路径。
本页讲创建会话、谁能加入、SDK,以及连接断掉时会发生什么。
curl -X POST https://dash.yunzheng.space/api/v1/talk/rooms \
-H "Authorization: Bearer $ORBIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Support","kind":"room"}'| 字段 | 含义 |
|---|---|
kind | room 按 retention_days 保留历史;live 只在内存留最近几百条,不落盘。 |
city | 落在哪座城市。套餐功能;不填则由余量最多的城市接收。历史也在那里,所以不会迁移。 |
max_peers、max_kbps、retention_days | 本会话的上限,不超过套餐允许值。超过会被拒绝,而不是被悄悄下调。 |
public_join | false 表示链接不再应答,只有你后端签发的令牌能进。 |
应答里有 key(链接)与 join_url(托管页)。用 PUT /talk/rooms/{id}/passcode 设口令;存的是哈希,读不回来。
<script src="https://talk.yunzheng.space/v1.js"></script>
<script>
var chat = OrbitTalk.join({
room: "<room key>",
label: "Ada",
passcode: "",
onMessage: function (m) { console.log(m.seq, m.label, m.body); },
onState: function (s, d) { if (s === "open") console.log("in, " + d.members + " here"); },
onPresence: function (p) { console.log(p.members + " here"); },
onError: function (e) { console.error(e.code, e.message); }
});
chat.send("Hello");
// later: chat.leave();
</script>send 立即返回一个 id,消息在连接允许时发出;连接断开时它在发件箱里等待,下次连上再发。你的应用不必自己写这个缓冲。
如果由你的后端决定谁能进——你的用户、用你给的名字——就关掉 public_join,在你的服务器上用 POST /talk/rooms/{id}/join 签发令牌(peer_id 填你的用户 id,label 填显示名),再通过 fetchJoin 交给 SDK。每次重连 SDK 都会再调一次,因为令牌只有两分钟有效。
OrbitTalk.join({
fetchJoin: function () {
// your server calls POST /talk/rooms/{id}/join with the caller's own id and name
return fetch("/my-api/chat-token", { method: "POST", credentials: "same-origin" })
.then(function (r) { return r.json(); });
},
onMessage: function (m) { /* m.peer is YOUR user id; m.label is the name you gave */ }
});消息存在承载该会话的那台机器上,不会被复制到控制面。你的账号可以用 GET /talk/rooms/{id}/history 一页一页读回来,凭的是你的 API 密钥——所以这个调用应当放在你的服务器上,和签发加入令牌的那段代码在一起。
var page = await OrbitTalk.history({ room: 12, key: process.env.ORBIT_TOKEN });
page.messages.forEach(function (m) { console.log(m.seq, m.at, m.label, m.body); });
// Walk forward: pass the page's "next" back as the cursor until it comes back null.
while (page.next != null) {
page = await OrbitTalk.history({ room: 12, key: process.env.ORBIT_TOKEN, cursor: page.next });
}| 字段 | 含义 |
|---|---|
cursor | 读这个序号之后的内容。第一次不填,之后把上一页的 next 传回来。 |
limit | 每页条数,1 到 500。默认 200——一屏的量,而不是全部。 |
next | 下一页的游标;如果已经读完则为 null。不满一页就说明没有更多了,所以它不会带游标。 |
messages[].peer | 发送者。走后端门时这就是你自己的用户 id——正因如此,一年后再看这段记录才还有意义。 |
每条消息都带会话分配的序号,SDK 记住它看到的最后一个。重连时只请求之后的内容,所以不重复、不遗漏。你发出的每条消息也带自己的 id,重置后重发会得到第一份已有的序号,而不会被存两次。
| 限额 | 含义 |
|---|---|
| 会话数 | 可以拥有多少个 |
| 并发连接 | 所有会话加起来同时在线的人数 |
| 每月消息数 | 每条只计一次,无论客户端重发多少次 |
| 每月流量 | 进出字节 |
| 历史天数 | 会话的上限;直播聊天不保留 |