跳到主要内容

注册用户

客户端在与即时通讯服务端建立连接时必须传入用户在即时通讯服务的身份验证令牌（Token）。Token 是用户在即时通讯服务中的唯一身份标识，无论是使用即时通讯服务或是实时音视频服务，均需要使用该 Token。获取 Token 即表示一个用户在即时通讯服务中完成注册。

在开始之前，我们建议先阅读用户概述，以了解用户管理的相关接口、服务及配置。

获取 Token​

客户端 SDK 不提供获取 Token 的 API。您需要在应用服务端（App Server）集成即时通讯服务端获取 Token API，实现获取 Token 的业务逻辑。

成功获取 Token 后，由您的应用服务端将 Token 分发给客户端。客户端在连接即时通讯服务端时使用。Token 在有效期内都可以正常使用。关于 Token 有效期的详细描述，详见作废 Token。

同一个用户 ID 可多次获取 Token，如果 Token 在有效期内，均可用于连接即时通讯服务。App 获取、使用 Token 进行连接、认证的参考方案与 UML 流程图可参考下文使用 Token。通过 App 层定义的用户 ID（userId）换取即时通讯服务中使用的身份验证 Token。同一用户 ID 如需重新获取 Token 使用同一接口。

危险

一旦您在控制台刷新 App Secret ，App Key 下已获取的 Token 均会失效。请使用新的 App Secret 生成 API 签名，并重新获取 Token。

请求方法​

POST： https://数据中心域名/user/getToken.json

签名规则： 所有服务端 API 请求均需要进行规则校验，详见 API 请求签名。

频率限制： 每秒钟限 200 次

正文参数​

HTTP 请求正文数据格式为 application/x-www-form-urlencoded，支持以下 HTTP 表单参数：

获取 Token 时传入的名称（name）和 头像（portraitUri），仅供移动端远程推送时使用。如需变更名称和头像信息，建议通过修改用户信息的方法进行变更。在重新获取 Token 时如果传入新的数据，则会覆盖旧的名称与头像数据。

参数类型必传说明
userIdString是App 自行定义的用户 ID，用于换取 Token。支持大小写英文字母与数字的组合，最大长度 64 字节。
nameString是推送服务使用的用户名称。不区分符号、英文字符、中文字符，统一限制最多 64 个字符。
portraitUriString否用户头像 URI，最大长度 1024 字节。
提示
  • 如果发送单聊会话消息，只需要 userId 即可定位到接收方。考虑到安全问题，强烈建议开发者注册用户时不要使用连续的 userId，以防止被恶意利用。
  • 部分旧版 Server SDK 中 portraitUri 字段为必填项；若不希望填写该字段，请升级 Server SDK 到最新版，或者传一个固定字符即可，比如："_"。

请求示例​

HTTP
POST /user/getToken.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1408710653491
Signature: 45beb7cc7307889a8e711219a47b7cf6a5b000e8
Content-Type: application/x-www-form-urlencoded

userId=jlk456j5&name=Ironman&portraitUri=http%3A%2F%2Fabc.com%2Fmyportrait.jpg

返回结果​

HTTP 响应正文包含具有以下结构的 JSON 对象：

返回值返回类型说明
codeInt返回码，200 为正常。
tokenString用户身份验证 Token，长度在 256 字节以内，可以保存应用内。Token 中携带 IM 服务动态导航地址，开发者不需要进行处理。
userIdString返回输入参数中提供的用户 ID。

返回结果示例​

HTTP
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200, "userId":"jlk456j5", "token":"sfd9823ihufi"}

使用 Token​

即时通讯服务不管理任何 App 用户信息。用户的注册仅需通过用户 ID 交换 Token 即可。

您的 App 客户端需要在建立 IM 连接时处理 Token 失效的情况，并且在 Token 失效时请求应用服务端重新获取 Token。

以下提供了基于 Token 认证与连接的方案，供您参考。

首次连接时获取 Token​

应用获取 Token 后，根据情况可选择在应用本地保留当前用户的 Token。流程如下：

非首次连接时使用已有 Token​

后续登录过程中，不必再向即时通讯服务端请求 Token，由应用服务端直接提供之前保存过的 Token。

提示
  • 请实现重新向服务器获取 Token 的代码逻辑，以处理 Token 失效的情况。
  • Token 具有有效期，默认为永久有效，可在控制台进行修改。
  • 刷新 App Secret、作废 Token 均可使已有 Token 失效。

如果您的 App 是免登录设计，也可以将 Token 保存在 App 本地（注意保证本地数据存储安全），直接登录。

最后于 更新