Token，也称动态密钥，是 app 用户在加入频道或登录服务系统时采用的一种鉴权方式。

本文展示如何使用 Agora 提供的代码在服务端生成 Token。

简介

Token 在你的业务服务端生成。用户加入频道或登录服务时，客户端需要向服务端申请 Token；服务器生成 Token 后，再将其传给客户端。

前提条件

开始前，请确保你的项目或使用的 Agora 产品满足如下条件：

• 你的 Agora 项目在控制台已开启 App 证书。

• 你所使用的 Agora 产品，满足如下版本要求：

  产品	支持 Token 的版本
  RTC SDK	Native SDK: v2.1.0 及以上 Web SDK: v2.4.0 及以上 第三方框架 SDK: 所有版本
  本地服务端录制 SDK	v2.1.0 及以上
  云端录制	无版本要求
  实时码流	所有版本
  互动游戏 SDK	v2.2.0 及以上

Token 代码说明

Agora 在 GitHub 提供一个开源的 AgoraDynamicKey 仓库，支持使用 C++、Java、Python、PHP、Ruby、Node.js、Go 等语言在你的服务端部署生成 Token。下图以 C++ 为例，展示生成 Token 代码的文件结构：

其中：

• ./sample/RtcTokenBuilderSample.cpp 文件包含用于生成 RTC Token 的示例代码。
• ./src/RtcTokenBuilder.h 文件包含用于生成 RTC Token 的 API 源代码。

使用示例代码快速生成 Token

Agora 在各语言的 sample 文件夹下提供了生成 Token 的示例代码供你参考。以 C++ 为例：

int main(int argc, char const *argv[]) {

  // 请填入你的项目 App ID
  std::string appID  = "970Cxxxxxxxxxxxxxxxxxxxxxxx1b33";
  // 请填入你的项目 App 证书
  std::string  appCertificate = "5CFdxxxxxxxxxxxxxxxxxxxxxxx5d3b";
  // 请填入频道名
  std::string channelName= "7d72xxxxxxxxxxxxxxxxxxxxxxbdda";
  // 请填入 uid。如果填 0，则表示不对 uid 鉴权
  uint32_t uid = 2882341273;
  // Token 服务过期时间
  uint32_t expirationTimeInSeconds = 3600;
  uint32_t currentTimeStamp = time(NULL);
  uint32_t privilegeExpiredTs = currentTimeStamp + expirationTimeInSeconds;
  std::string result;

  result = RtcTokenBuilder::buildTokenWithUid(
      appID, appCertificate, channelName, uid, UserRole::Role_Publisher,
      privilegeExpiredTs);
  std::cout << "Token With Int Uid:" << result << std::endl;

你可以参考如下步骤，通过命令行直接使用上述示例代码生成 Token。开始前请确保已安装 OpenSSL 库。

1. 将 AgoraDynamicKey 仓库下载或克隆至本地。

2. 打开 AgoraDynamicKey/cpp/sample/RtcTokenBuilderSample.cpp 文件，使用自己的 App ID、App 证书、用户 ID 以及频道名替换示例代码中的值，并注释掉示例代码中的 buildTokenWithUserAccount 代码片段。

3. 进入 RtcTokenBuilderSample.cpp 所在路径，然后运行如下命令行。运行结束后，相同文件夹下会生成一个可执行文件 RtcTokenBuilderSample。

    g++ -std=c++0x -O0 -I../../ -L. RtcTokenBuilderSample.cpp -lz -lcrypto -o RtcTokenBuilderSample

4. 运行如下命令行生成 Token。生成的 Token 会显示在 Terminal 中。

    ./RtcTokenBuilderSample

使用其他语言的示例代码在本地生成 Token 的步骤如下：

Python -V

Python -V

ruby -version

API 参考

下文以 C++ 的 API 为例，介绍生成 Token 的 API 参数含义。具体参数解释也适用于其他语言。

static std::string buildTokenWithUid(
    const std::string& appId,
    const std::string& appCertificate,
    const std::string& channelName,
    uint32_t uid,
    UserRole role,
    uint32_t privilegeExpiredTs = 0);

开发注意事项

参数匹配

生成 Token 时填入的频道名和用户 ID，需要和加入频道时填入的参数一致。

App 证书与 Token

生成 Token 需要先在控制台启用对应项目的 App 证书。项目一旦开启了 App 证书，就必须使用 Token 鉴权。

Token 过期

Token 的最大有效期为 24 小时。为保证通信体验，Agora 会在 Token 即将过期或已经过期时，分别触发以下回调：

• onTokenPrivilegeWillExpire：该回调表示 Token 即将失效。
• onRequestToken（Web 平台为 onTokenPrivilegeDidExpire）：该回调表示 Token 已经失效。

收到任一回调后，你需要在服务端重新生成 Token，然后调用 renewToken 方法更新 Token。

相关链接

生成 Token 过程中，你也可以参考如下文档：

• 如何处理 Token 相关错误码
• 如何处理云端录制 101 错误码
• 如何使用连麦鉴权功能