产品 / 插件:即时通讯
平台 / 框架:iOS / Android / macOS / Windows / Flutter / React Native / uni-app / Unity3D
更新时间:2023-05-15 18:33
为了提高项目的安全性,对于使用 AppSign 鉴权的开发者,可以使用 Token 鉴权、且鉴权通过后才能使用相关服务(如果您不需要,可继续使用 AppSign 鉴权方式),您可以参考本文档进行升级。
开始支持 “AppSign 鉴权” 的 SDK 版本:
所有版本的 SDK,均支持 “Token 鉴权”。
ZIM SDK 提供了如下 “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 技术支持处理。2.3.0 ~ 2.3.1
版本。2.3.0
版本。2.3.0 以下
版本的 SDK,默认为 “Token 鉴权”,不支持 “AppSign 鉴权”,无需另行开通。开发者客户端向开发者服务端发送请求申请 Token,由开发者服务端生成 Token 后返回给到对应客户端。
ZEGO 在 GitHub/Gitee 提供了一个开源的 zego_server_assistant 插件,支持使用 Go、C++、Java、Python、PHP、.NET、Node.js 语言,在开发者的服务端或客户端部署生成 Token(不推荐客户端生成)。
生成 Token 的详细介绍请参考如下文档:
本章主要介绍您升级 SDK 后如何使用 Token 功能。
各平台的实现流程如下:
iOS/macOS
调用 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
调用 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
调用 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
调用 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
调用 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
调用 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');
};
联系我们
文档反馈