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

产品 / 插件：即时通讯

平台 / 框架：iOS / Android / macOS / Windows / Flutter / React Native / uni-app / Unity3D

更新时间：2023-05-15 18:33

文档导读

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

开始支持 “AppSign 鉴权” 的 SDK 版本：
- iOS/Android/macOS/Windows：2.3.0 及以上版本，2022-08-12 发布。
- uni-app/React Native：2.3.0 及以上版本，2022-08-30 发布。
- Flutter：2.3.0 及以上版本，2022-09-02 发布。
- 其余平台：暂不支持 AppSign 鉴权。
所有版本的 SDK，均支持 “Token 鉴权”。

方案说明

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

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

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

鉴权方式

鉴权方式	功能描述	安全级别
AppSign 鉴权	在创建 ZIM 实例时传入 AppSign，鉴权通过后即可使用 ZIM 功能。请在登录 ZIM 时，给 Token 传入空字符串或不传。	安全级别很低。原因为：如果 AppSign 被泄漏，攻击者会盗用您的云服务流量，并且 AppSign 没有过期机制，建议您尽快升级为 Token 鉴权。
Token 鉴权（推荐）	Token 鉴权是在登录 ZIM 时必须传入 Token，鉴权通过后即可使用实时音视频功能。请在创建 ZIM 实例时，给 AppSign 传入空字符串或不传。	安全级别高。原因为：通过开发者自建服务端下发 Token，并且在客户端上进行认证，且下发的 Token 具有时效性。因此，我们推荐您使用 Token 鉴权。

当您同时传入了 AppSign 和 Token 时（不建议同时传入），将先校验 AppSign，若 AppSign 校验通过，则不再校验 Token；如果 AppSign 校验不通过，则再校验 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 的详细介绍请参考如下文档：

产品	参考文档
即时通讯	iOS Android macOS Windows uni-app React Native Flutter

使用 Token

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

产品	平台
即时通讯	iOS Android macOS Windows uni-app React Native Flutter

各平台的实现流程如下：

iOS/macOS

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

调用 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];

调用 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) {
    //这里填写登录的回调
}];

在收到的 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

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

调用 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);

调用 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 来判断是否登录成功。          
    }
});

在收到的 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

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

调用 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);

调用 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){
    // 这里可以获取登录结果返回值，并根据错误码执行用户代码
});

在收到的 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

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

调用 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();

调用 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) {
        // 登录失败
    });

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

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

React Native

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

调用 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();

调用 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) {
        // 登录失败
    });

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

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

Flutter

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

调用 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);

调用 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:
    }
});

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

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

本文档是否帮助你解决问题？

有帮助

没有帮助

如果遇到产品相关问题，您可以创建工单寻求帮助

常见问题

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

文档导读

方案说明

鉴权方式

升级指导

服务开通

生成 Token

使用 Token