跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

参与者

最后更新 查看 MarkdownAgent 设置

在用户可以通过 RealtimeKit SDK 加入会议之前,您的后端必须使用 Add Participant API 将该用户作为参与者添加到该会议中。 在 RealtimeKit 中,参与者(participant) 代表被允许加入特定会议的用户。

您可以把这想象成学生注册进课堂。会议就是课堂,而添加参与者就是您注册用户以允许他们出席的方式。

当您添加参与者时,您还需要选择应用哪个预设(preset)。预设定义了该参与者的角色、权限和会议体验。

参与者令牌

当您使用 Add Participant API 端点将参与者添加到会议时,它会返回:

  • 标识该参与者在会议中的参与者 id。
  • 该参与者的身份验证令牌 token。

您的后端应该将其提供给您的前端应用程序。当用户选择加入会议时,前端将该令牌传递给 RealtimeKit SDK。

RealtimeKit 使用令牌对参与者进行身份验证,并确定哪个会议和哪个参与者正在加入。如果没有有效的身份验证令牌,SDK 就无法代表该参与者加入会议。只要参与者拥有有效的身份验证令牌,该参与者就可以随着时间的推移加入同一会议的多个活动会话期(session)。

令牌有效性与刷新

参与者身份验证令牌是 JSON Web Token(JWT)。meetingId 和 participantId 字段将每个令牌限定为一次会议中的一名参与者。

默认情况下,令牌签发后立即生效,并在 100 天后过期。如需设置自定义有效期,请在添加参与者时于 token 对象中传入 not_before 和 expires_on,或在刷新令牌时于请求正文中传入。两个字段都是可选的 RFC 3339 时间戳,需带时区偏移,例如 2026-10-01T09:00:00Z(UTC)或 2026-10-01T14:30:00+05:30:

  • not_before 默认为当前时间,也可以设为过去的时间。
  • expires_on 默认为 not_before 之后 100 天,并且必须是未来时间。
  • 有效期不得超过 100 天。

响应会以 UTC 返回已签发令牌的 not_before 和 expires_on 值。

你的后端可以在令牌过期之前或之后调用 Refresh Participant Token 端点。新令牌沿用现有参与者记录,包括其参与者 id 和预设。刷新不会使先前签发的令牌失效。每个令牌在其自身过期时间之前都保持有效。

撤销令牌

如需撤销单个令牌,请向 /accounts/{account_id}/realtime/kit/{app_id}/meetings/{meeting_id}/participants/{participant_id}/token 发送 DELETE 请求,并在请求正文中传入令牌:

{
    "token": "<PARTICIPANT_AUTH_TOKEN>"
}

该参与者的其他令牌仍然有效。

令牌被撤销后,所有位置最多可能需要 60 秒才会拒绝该令牌。在此期间,参与者可能仍可使用被撤销的令牌重新加入会议。如需立即阻止所有参与者令牌的访问,请改为删除参与者。

如需撤销参与者在某场会议中的所有令牌,请调用删除参与者端点。

撤销令牌或删除参与者,也会将其从会议的活动会话中移除(如果存在活动会话)。

参与者无法使用已过期、尚未生效或已撤销的令牌加入会议。RealtimeKit UI 和 Core SDK 会将该令牌报告为无效。RealtimeKit 会在参与者进入会议舞台之前将其拒绝,因此不会计费。API 错误响应会包含 reason 字段,其值可能是 participant_token_expired、participant_token_not_yet_valid、participant_token_revoked 或 participant_token_invalid。

自定义参与者标识符

在添加参与者时,您还可以选择提供一个自定义参与者标识符,称为 custom_participant_id。此值完全由您使用。 RealtimeKit 会存储它并在 API 中返回,但不会使用它来控制访问。它允许您将应用程序的用户映射到 RealtimeKit 参与者,并将 RealtimeKit 会话数据、事件或分析与您系统中的用户信息相关联。

后续步骤

在理解参与者后,您可以探索以下主题:

这篇文档对您有帮助吗?