开始使用
Orbit 账户的组织方式、控制台各处的功能,以及从登录到让我们的网络开始应答一个域名的最短路径。
Realtime(房间)
房间,以及进入房间的两条路。
房间由你创建,由你分发给的任何人加入。本页讲创建房间、链接形式、嵌入形式,以及房间可以设在门口的条件。
01
创建房间
可以在控制台创建,也可以用带写权限的令牌通过 API 创建。创建时需要名称与人数上限;其余每一项都有默认值,之后都可以修改。
curl -X POST https://dash.yunzheng.space/api/v1/rtc/rooms \
-H "Authorization: Bearer $ORBIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Weekly sync","max_peers":12,"max_video":4}'应答里包含房间的标识;链接入口开启时,还包含可以分发的地址。这两项在控制台里同样能看到 —— API 看到的就是同一个房间,只是换了一个视角。
| 字段 | 含义 |
|---|---|
name | 房间名称,最多 60 个字符。 |
max_peers | 同时在房间里的人数,2 到 50。 |
max_video | 其中可以发送视频的人数,默认 0,即语音房间。 |
public_join | 房间是否响应它的链接。关闭后只能通过你自己的服务进入。 |
passcode | 只写字段。设置后即要求口令,传空字符串表示取消。 |
require_verify | 放人进来之前是否执行人机验证。 |
verify_level | standard、strict 或 maximum。 |
max_video 与 max_peers 分开,是因为一路摄像头与一路麦克风的流量并不相同。十个人听、两路摄像头,与十路摄像头,是完全不同的负载;两个数字让你能说清楚你要的是哪一种。02
链接
链接入口开启时,房间通过它自己的地址即可访问,访客无需安装任何东西。页面会向浏览器申请麦克风;房间允许视频时,也会申请摄像头。
https://rtc.yunzheng.space/r/<room key>像分发任何地址一样把它发出去。拿到它的人都能打开房间 —— 这也正是重要的房间应当同时设置口令、人机验证,或两者兼有的原因。
03
嵌入你自己的页面
一行 script 标签,再加一次调用。这个库没有依赖、不需要构建步骤,而且它自己不绘制任何界面:它把媒体流交给你,由你放进自己的排版里。
<script src="https://rtc.yunzheng.space/v1.js"></script>
<script>
OrbitRTC.room("<room key>").then(function (room) {
// room.needs_passcode / room.needs_verify say what to ask for first.
return OrbitRTC.join({
room: "<room key>",
label: "Ada",
passcode: room.needs_passcode ? prompt("Passcode") : "",
video: false,
onTrack: function (stream) {
var el = document.createElement("audio");
el.srcObject = stream;
el.autoplay = true;
document.body.appendChild(el);
},
onError: function (err) { console.error(err.code, err.message); }
});
}).then(function (session) {
window.addEventListener("pagehide", function () { session.leave(); });
});
</script>在渲染表单之前先问房间需要什么,而不是被拒绝之后才知道:OrbitRTC.room() 会告诉你是否需要口令与人机验证,页面因此可以一次性给出正确的提示。
如果你的页面发送
Content-Security-Policy:库从 https://rtc.yunzheng.space 加载,加入房间时使用 https: 与 wss:。要求人机验证的房间还会从 https://verify.yunzheng.space 加载验证组件。04
门口的条件
房间在放人进来之前检查条件,因此一次拒绝既没有代价,也不会泄露房间里有谁。
- 口令 —— 设在房间上,设定之后 API 不再返回它。修改口令后,旧口令立即失效。
- 人机验证 —— 级别为
standard、strict或maximum。级别本身就是校验内容的一部分:在standard下取得的令牌,不能满足设为maximum的房间。 - 完全不开链接 —— 关闭链接入口后,房间地址谁也放不进来,只有你构建的服务能决定谁进入。
05
房间跑在哪里
房间跑在一座城市里,控制台会标明是哪一座。城市在第一次有人加入时确定,并且在房间里有人期间不再更换 —— 更换房间所在城市意味着把里面的所有人踢下线。
房间内容不会被录制。没有可以开启的录制功能,也不存在对房间内所说、所展示内容的任何留存副本。
06
常见问题
我可以有多少个房间?
取决于账户所持的服务包。控制台会显示这个数量;超出后创建会被拒绝,应答中会写明该限额。
可以把参与者请出房间吗?
目前不能在房间内部移除参与者。可行的做法是修改口令或停用房间,两者都在下一次放人时生效。
房间标识会过期吗?
不会。它属于房间,与房间同寿。删除房间即可让它的地址失效。