使用 Token 鉴权

---

功能简介

使用 Token 鉴权，指用户在初始化 ZEGO MiniGameEngine SDK 时，ZEGO 的服务端会根据用户初始化时携带的 Token 参数，判断用户是否有权限使用小游戏服务，避免因权限控制缺失或操作不当引发的风险问题。

实现原理

用户初始化 ZEGO MiniGameEngine SDK 之前，您的服务端应先生成 Token，ZEGO 服务端会对带着 Token 的用户进行校验，根据 Token 参数判断用户是否为合法用户。

初始化时 Token 校验的流程如下图：

1. 客户端发起申请 Token 的请求。
2. 在开发者的服务端上生成 Token，并返回给客户端。
3. 客户端携带申请到的 Token 初始化 ZEGO MinGameEngine SDK。
4. ZEGO MiniGameEngine SDK 会自动将 Token 发送到 ZEGO 服务端进行校验。
5. ZEGO 服务端会将校验的结果返回给 ZEGO MinGameEngine SDK。
6. ZEGO MinGameEngine SDK 再将校验的结果直接返回给客户端，没有权限的客户端初始化将失败。

前提条件

在使用 Token 鉴权之前，请确保已在项目中集成 ZEGO MiniGameEngine SDK，详情请参考 集成 SDK。

使用步骤

以下将介绍开发者的服务端如何生成 Token、如何使用 SDK 设置 Token、以及 Token 过期时的处理方式。

1 生成 Token

1.1 获取 AppID 和 ServerSecret。

前往 ZEGO 控制台 创建项目，获取接入小游戏服务所需的 AppID 和 ServerSecret。随后联系 ZEGO 商务人员开通小游戏服务。

1.2 开发者服务端生成 Token。

为方便开发者使用，ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件，支持使用 Go、C++、Java、Python、PHP、.NET、Node.js 等语言，在开发者的服务端部署生成 Token。

以 Go 语言为例，开发者可参考以下步骤使用 zego_server_assistant 生成 Token：

1. 首先将 “go/zegoserverassistant” 目录，拷贝到开发者的服务端项目中。
2. 使用命令 import zsa "your-project-go-mod-path/zegoserverassistant" 引入插件，需要将 “your-project-go-mod-path” 替换为开发者自己的项目名称。
3. 调用插件提供的 GenerateToken04 方法生成 Token。

var appId uint32 = <Your AppId>   // 在 ZEGO 控制台创建项目后获取的 AppID，类型为 uint32
userId := <Your userID>  // 有您定义的用户 ID，类型为 string
secret := <ServerSecret>  // 在 ZEGO 控制台创建项目后获取的 AppID，是长度为 32 字节的 string
var effectiveTimeInSeconds int64 = <Your token effectiveTime> // Token 有效时长，类型为 int64，单位为秒(s)

token, err := zsa.GenerateToken04(appId, userId, secret, effectiveTimeInSeconds)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(token)

2 设置 Token

用户在调用 init 接口初始化 ZEGO MiniGameEngine SDK 时传入 Token。

// 请先初始化 ZEGO Express SDK，否则无法收到下面 init 接口的回调

// 创建 ZEGO Mini Game Engine 实例对象。
ZegoMiniGameEngine miniGameEngine = ZegoMiniGameEngine.getInstance();

// 初始化 ZEGO Mini Game Engine SDK
// appID 在 [ZEGO 控制台](https://console.zego.im/) 创建项目后获得，格式为：appID + L，如：1234567890L
// 详情请参考文档 [控制台 - 项目信息](https://doc-zh.zego.im/article/12107)
long appID = appID;
String token = "your token"; // 从您的服务器获取到的 Token
String userID = "your user ID"; // 自定义的用户 ID
String userName = "your user name"; // 自定义的用户名称
String userAvatar = "your user avatar"; // 用户头像 URL
ZegoGameUserInfo userInfo = new ZegoGameUserInfo(userID, userName, userAvatar);
miniGameEngine.init(appID, token, userInfo, (errorCode, object) -> {});

3 处理 Token 过期

在 Token 过期前 30 秒，SDK 会通过 onTokenWillExpire 回调发出通知。

收到该回调后，您需要从自己的服务端获取新的有效 Token，并调用 SDK 提供的 updateToken 接口更新 Token。

// 更新 Token
miniGameEngine.updateToken(token);