ZIM 如何从 AppSign 鉴权升级为 Token 鉴权？

文档导读

为了提高项目的安全性，对于使用 AppSign 鉴权的开发者，可以使用 Token 鉴权、且鉴权通过后才能使用相关服务（如果您不需要，可继续使用 AppSign 鉴权方式），您可以参考本文档进行升级。

方案说明

ZIM SDK 提供了如下 “Token 鉴权” 的接入方案：

在此方案中，您需要通过您自己的业务系统实现以下业务逻辑：

• 搭建客户端的用户管理逻辑，并下发用户 ID 用于客户端登录。
• 鉴权 Token，建议由您的业务后台自行实现，保证鉴权数据安全。

鉴权方式

升级指导

服务开通

• 2.3.3 及以上 版本的 SDK，支持鉴权方式的自主切换，无需联系 ZEGO 技术支持处理。
• 以下版本的 SDK，需要切换为 “Token 鉴权” 时，请联系 ZEGO 技术支持处理。
  • iOS/Android/macOS/Window：2.3.0 ~ 2.3.1 版本。
  • uni-app/React Native/Flutter：2.3.0 版本。
• 2.3.0 以下 版本的 SDK，默认为 “Token 鉴权”，不支持 “AppSign 鉴权”，无需另行开通。

生成 Token

开发者客户端向开发者服务端发送请求申请 Token，由开发者服务端生成 Token 后返回给到对应客户端。

ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件，支持使用 Go、C++、Java、Python、PHP、.NET、Node.js 语言，在开发者的服务端或客户端部署生成 Token（不推荐客户端生成）。

生成 Token 的详细介绍请参考如下文档：

使用 Token

本章主要介绍您升级 SDK 后如何使用 Token 功能。

各平台的实现流程如下：

iOS/macOS

1. 已下载并集成最新版本的 SDK，详情请参考 集成 SDK。

2. 调用 createWithAppConfig 接口创建 ZIM 实例时，ZIMAppConfig 中的 “AppSign” 传空或者不传。

   // 创建 ZIM 对象，传入 appID、appSign
   // 请注意：ZIM 从 2.3.0 版本开始支持 AppSign 鉴权，SDK 也默认为 AppSign 鉴权，如果您需要切换鉴权方式：
   // (1) 2.3.3 及以上版本的 SDK，支持鉴权方式的自主切换; (2) 2.3.0 ~ 2.3.1 版本的 SDK，需要切换为 “Token 鉴权” 时，请联系 ZEGO 技术支持处理
   ZIMAppConfig *appConfig = [[ZIMAppConfig alloc] init];
   appConfig.appID = (unsigned int)appID;     //替换为您申请到的 AppID
   appConfig.appSign = @"appSign";     //AppSign 传空或者不传
   self.zim = [ZIM createWithAppConfig: appConfig];

3. 调用 loginWithUserInfo 接口登录 ZIM 时，需要填入开发者服务器生成的 Token。

   // userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
   // userName 最大 64 字节的字符串，无特殊字符限制。
   ZIMUserInfo *userInfo = [[ZIMUserInfo alloc]init];
   userInfo.userID = @"zegoUser1"; //填入NSString类型的值
   userInfo.userName = @"zegotest";//填入NSString类型的值
   
   // 登录时：
   // 使用 Token 鉴权，需要开发者填入 "使用 Token 鉴权" 文档生成的 Token，详情请参考 [使用 Token 鉴权]
   [zim loginWithUserInfo:userInfo token:token callback:^(ZIMError * _Nonnull errorInfo) {
       //这里填写登录的回调
   }];

4. 在收到的 tokenWillExpire 回调后，调用 renewToken 接口更新 Token 并传入 SDK 即可。

   - (void)zim:(ZIM *)zim tokenWillExpire:(unsigned int)second {
       NSString *token = [MyToken getToken]; // 重新请求开发者服务端获取 Token
       [self.zim renewToken:token callback:^(ZIMError * _Nonnull errorInfo) {
           // 开发者可根据 ZIMErrorCode 来判断更新 Token 是否成功。
           ......
       }];
   }

Android

1. 已下载并集成最新版本的 SDK，详情请参考 集成 SDK。

2. 调用 create 接口创建 ZIM 实例时，ZIMAppConfig 中的 “AppSign” 传空或者不传。

   // 创建 ZIM 对象，传入 appID、appSign 与 Android 中的 Application
   // 请注意：ZIM 从 2.3.0 版本开始支持 AppSign 鉴权，SDK 也默认为 AppSign 鉴权，如果您需要切换鉴权方式：
   // (1) 2.3.3 及以上版本的 SDK，支持鉴权方式的自主切换; (2) 2.3.0 ~ 2.3.1 版本的 SDK，需要切换为 “Token 鉴权” 时，请联系 ZEGO 技术支持处理
   ZIMAppConfig appConfig = new ZIMAppConfig();
   appConfig.appID = 12345;  //替换为您申请到的 AppID
   appConfig.appSign = "appSign";   //AppSign 传空或者不传
   zim = ZIM.create(appConfig, application);

3. 调用 login 接口登录 ZIM 时，需要填入开发者服务器生成的 Token。

   // userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
   // userName 最大 64 字节的字符串，无特殊字符限制。
   ZIMUserInfo zimUserInfo = new ZIMUserInfo();
   zimUserInfo.userID = userID;
   zimUserInfo.userName = userName;
   
   // 登录时：
   // 使用 Token 鉴权，需要开发者填入 "使用 Token 鉴权" 文档生成的 Token，详情请参考 [使用 Token 鉴权]
   zim.login(zimUserInfo, token, new ZIMLoggedInCallback() {
       @Override
       public void onLoggedIn(ZIMError error) {
           // 开发者可根据 ZIMError 来判断是否登录成功。          
       }
   });

4. 在收到的 onTokenWillExpire 回调后，调用 renewToken 接口更新 Token 并传入 SDK 即可。

   @Override
   public void onTokenWillExpire(int second){
       String token = getToken(); // 重新请求开发者服务端获取 Token;
       engine.renewToken(token, new ZIMTokenRenewedCallback {
           @Override
           public void onTokenRenewed(String token, ZIMError error) {
               // 开发者可根据 ZIMError 来判断更新 Token 是否成功
           } 
       });
   }

Windows

1. 已下载并集成最新版本的 SDK，详情请参考 集成 SDK。

2. 调用 create 接口创建 ZIM 实例时，ZIMAppConfig 中的 “AppSign” 传空或者不传。

   // 创建 ZIM 对象，传入 appID、appSign，目前仅建议一个客户端创建一个zim实例
   // 请注意：ZIM 从 2.3.0 版本开始支持 AppSign 鉴权，SDK 也默认为 AppSign 鉴权，如果您需要切换鉴权方式：
   // (1) 2.3.3 及以上版本的 SDK，支持鉴权方式的自主切换; (2) 2.3.0 ~ 2.3.1 版本的 SDK，需要切换为 “Token 鉴权” 时，请联系 ZEGO 技术支持处理
   zim::ZIMAppConfig app_config;
   app_config.appID = 12345;     //替换为您申请到的 AppID
   app_config.appSign = "appSign";   //AppSign 传空或者不传
   zim_ = zim::ZIM::create(app_config);

3. 调用 login 接口登录 ZIM 时，需要填入开发者服务器生成的 Token。

   // userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
   // userName 最大 64 字节的字符串，无特殊字符限制。
   zim::ZIMUserInfo user_info;
   user_info.userID = user_id;
   user_info.userName = user_name;
   
   // 登录时：
   // 使用 Token 鉴权，需要开发者填入 "使用 Token 鉴权" 文档生成的 Token，详情请参考 [使用 Token 鉴权]
   zim_->login(user_info, token, [=](zim::ZIMError errorInfo){
       // 这里可以获取登录结果返回值，并根据错误码执行用户代码
   });

4. 在收到的 onTokenWillExpire 回调后，调用 renewToken 接口更新 Token 并传入 SDK 即可。

   void onTokenWillExpire(ZIM * zim, unsigned int second) override {
       std::string token = getToken(); // 重新请求开发者服务端获取 Token
       zim->renewToken(token, [=](const std::string &token, zim::ZIMError errorInfo) {
           // 开发者可根据 errorInfo 中的 code 来判断更新 Token 是否成功
           ......
       });
   }

uni-app

1. 已下载并集成最新版本的 SDK，详情请参考 集成 SDK。

2. 调用 create 接口创建 ZIM 实例时，ZIMAppConfig 中的 “AppSign” 传空或者不传。

   // 请注意：ZIM 从 2.3.0 版本开始支持 AppSign 鉴权，SDK 也默认为 AppSign 鉴权，如果您需要切换鉴权方式：
   // (1) 2.3.3 及以上版本的 SDK，支持鉴权方式的自主切换; (2) 2.3.0 版本的 SDK，需要切换为 “Token 鉴权” 时，请联系 ZEGO 技术支持处理
   
   // 静态同步方法，创建 zim 实例，传入 AppID 和 AppSign
   // create 方法仅第一次调用时会创建 ZIM 实例，后续调用会返回 null。
   ZIM.create({ appID: 0, appSign: '' });
   // 通过 getInstance 获取单实例，避免热更新导致 create 多次创建返回 null。
   var zim = ZIM.getInstance();

3. 调用 login 接口登录 ZIM 时，需要填入开发者服务器生成的 Token。

   // userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
   // userName 最大 64 字节的字符串，无特殊字符限制。
   var userInfo = { userID: 'xxxx', userName: 'xxxx' };
   
   // 登录时：
   // 使用 Token 鉴权，需要开发者填入 "使用 Token 鉴权" 文档生成的 Token，详情请参考 [使用 Token 鉴权]
   var token = '';
   zim.login(userInfo, token)
       .then(function () {
           // 登录成功
       })
       .catch(function (err) {
           // 登录失败
       });

4. 在收到的 tokenWillExpire 回调后，调用 renewToken 接口更新 Token 并传入 SDK 即可。

   // 注册监听“令牌即将过期”的回调
   zim.on('tokenWillExpire', function(zim, second) {
       var token = ''; // 重新请求开发者服务端获取 Token
       zim.renewToken(token)    
           .then(function({ token }) {
               // 更新成功
           })
           .catch(function(err) {
               // 更新失败
           });
   })

React Native

1. 已下载并集成最新版本的 SDK，详情请参考 集成 SDK。

2. 调用 create 接口创建 ZIM 实例时，ZIMAppConfig 中的 “AppSign” 传空或者不传。

   // 请注意：ZIM 从 2.3.0 版本开始支持 AppSign 鉴权，SDK 也默认为 AppSign 鉴权，如果您需要切换鉴权方式：
   // (1) 2.3.3 及以上版本的 SDK，支持鉴权方式的自主切换; (2) 2.3.0 版本的 SDK，需要切换为 “Token 鉴权” 时，请联系 ZEGO 技术支持处理
   
   // 静态同步方法，创建 zim 实例，传入 AppID 和 AppSign
   // create 方法仅第一次调用时会创建 ZIM 实例，后续调用会返回 null。
   ZIM.create({ appID: 0, appSign: '' });
   // 通过 getInstance 获取单实例，避免热更新导致 create 多次创建返回 null。
   var zim = ZIM.getInstance();

3. 调用 login 接口登录 ZIM 时，需要填入开发者服务器生成的 Token。

   // userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
   // userName 最大 64 字节的字符串，无特殊字符限制。
   var userInfo = { userID: 'xxxx', userName: 'xxxx' };
   
   // 登录时：
   // 使用 Token 鉴权，需要开发者填入 "使用 Token 鉴权" 文档生成的 Token，详情请参考 [使用 Token 鉴权]
   var token = '';
   zim.login(userInfo, token)
       .then(function () {
           // 登录成功
       })
       .catch(function (err) {
           // 登录失败
       });

4. 在收到的 tokenWillExpire 回调后，调用 renewToken 接口更新 Token 并传入 SDK 即可。

   // 注册监听“令牌即将过期”的回调
   zim.on('tokenWillExpire', function(zim, second) {
       var token = ''; // 重新请求开发者服务端获取 Token
       zim.renewToken(token)    
           .then(function({ token }) {
               // 更新成功
           })
           .catch(function(err) {
               // 更新失败
           });
   })

Flutter

1. 已下载并集成最新版本的 SDK，详情请参考 集成 SDK。

2. 调用 create 接口创建 ZIM 实例时，ZIMAppConfig 中的 “AppSign” 传空或者不传。

   // 创建 
   // 通过插件创建 ZIM 单实例，传入 APPID、AppSign
   // 请注意：ZIM 从 2.3.0 版本开始支持 AppSign 鉴权，SDK 也默认为 AppSign 鉴权，如果您需要切换鉴权方式，请联系 ZEGO 技术支持切换配置
   ZIMAppConfig appConfig = ZIMAppConfig();
   appConfig.appID = appID;
   appConfig.appSign = appSign;  //AppSign 传空或者不传
   
   ZIM.create(appConfig);

3. 调用 login 接口登录 ZIM 时，需要填入开发者服务器生成的 Token。

   // userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
   // userName 最大 64 字节的字符串，无特殊字符限制。
   ZIMUserInfo userInfo = ZIMUserInfo();
   userInfo.userID = "userID"; //填入 string 类型的值
   userInfo.userName = "userName";//填入 string 类型的值
   
   // 登录时：
   // 使用 Token 鉴权，需要开发者填入 "使用 Token 鉴权" 文档生成的 Token，详情请参考 [使用 Token 鉴权]
   
   ZIM
   .getInstance()
   !.login(userInfo, "token")
   .then((value) {
       //登录成功触发此处
   })
   .catchError((onError) {
       switch (onError.runtimeType) {
           // 登录失败触发此处
           case PlatformException:
               log(onError.code); //登录失败错误码
               log(onError.message!);//登录失败错误信息
               break;
           default:
       }
   });

4. 在收到的 onTokenWillExpire 回调后，调用 renewToken 接口更新 Token 并传入 SDK 即可。

   ZIMEventHandler.onTokenWillExpire = (zim, second) {
       ZIM.getInstance().renewToken('new token');
   };