初始化
功能描述
在使用 IM SDK 的各项功能前,必须先进行初始化。
大多数场景下,在应用生命周期内,您只需要进行一次 IM SDK 初始化。
初始化
初始化 SDK 需要操作以下步骤:
1. 准备 SDKAppID。
2. 设置 LogLevelEnum。
3. 设置 SDK 事件监听器。
4. 调用
initSDK
初始化 SDK。下文我们将依次为您详细讲解具体的步骤内容。
准备 SDKAppID
您必须拥有正确的 SDKAppID,才能进行初始化。
SDKAppID 是腾讯云 IM 服务用于区分客户帐号的唯一标识。我们建议每一个独立的 App 都申请一个新的 SDKAppID。不同 SDKAppID 之间的消息是天然隔离的,不能互通。
设置 LogLevelEnum
设置日志级别
IM SDK 支持多种日志级别,如下表所示:
日志级别 | LOG 输出量 |
LogLevelEnum.V2TIM_LOG_NONE | 不输出任何 log |
LogLevelEnum.V2TIM_LOG_DEBUG | 输出 DEBUG,INFO,WARNING,ERROR 级别的 log (默认的日志级别) |
LogLevelEnum.V2TIM_LOG_INFO | 输出 INFO,WARNING,ERROR 级别的 log |
LogLevelEnum.V2TIM_LOG_WARN | 输出 WARNING,ERROR 级别的 log |
LogLevelEnum.V2TIM_LOG_ERROR | 输出 ERROR 级别的 log |
SDK 日志存储规则如下:
IM SDK 本地日志默认保存 7 天;SDK 在初始化时,会自动清理 7 天之前的日志。
在 Android 平台上,IM SDK 的日志在 4.8.50 版本之前默认存储于
/sdcard/tencenet/imsdklogs/应用包名
目录下,4.8.50 及之后的版本存储于 /sdcard/Android/data/包名/files/log/tencent/imsdk
目录下。从 4.7.1 版本开始,IM SDK 的日志开始采用微信团队的 xlog 模块进行输出。xlog 日志默认是压缩的,需要使用 Python 脚本进行解压。
获取解压脚本:若使用 Python 2.7,则单击 Decode Log 27 获取解压脚本;若使用 Python 3.0,则单击 Decode Log 30 获取解压脚本。
在 Windows 或者 Mac 控制台输入如下命令即可对 log 文件进行解压,解压后的文件以 xlog.log 结尾,可以直接使用文本编辑器打开。
python decode_mars_nocrypt_log_file.py imsdk_yyyyMMdd.xlog
设置 SDK 事件监听器
SDK 初始化后,会通过
V2TimSDKListener
抛出一些事件,例如连接状态、登录票据过期等。
我们建议您在调用initSDK时传入 V2TimSDKListener
(Dart) 接口添加 SDK 事件监听器,在对应回调中做一些逻辑处理。V2TimSDKListener
相关回调如下表所示:事件回调 | 事件描述 | 推荐操作 |
onConnecting | 正在连接到腾讯云服务器 | 适合在 UI 上展示 “正在连接” 状态。 |
onConnectSuccess | 已经成功连接到腾讯云服务器 | - |
onConnectFailed | 连接腾讯云服务器失败 | 提示用户当前网络连接不可用。 |
onKickedOffline | 当前用户被踢下线 | 此时可以 UI 提示用户 “您已经在其他端登录了当前帐号,是否重新登录?” |
onUserSigExpired | 登录票据已经过期 | 请使用新签发的 UserSig 进行登录。 |
onSelfInfoUpdated | 当前用户的资料发生了更新 | 可以在 UI 上更新自己的头像和昵称。 |
注意:
如果收到
onUserSigExpired
回调,说明您登录用的 UserSig 票据已经过期,请使用新签发的 UserSig 进行重新登录。如果继续使用过期的 UserSig,会导致 IM SDK 登录进入死循环。调用初始化接口
示例代码如下:
// 1. 从即时通信 IM 控制台获取应用 SDKAppID。int sdkAppID = 0;// 2. 添加 V2TimSDKListener 的事件监听器,sdkListener 是 V2TimSDKListener 的实现类V2TimSDKListener sdkListener = V2TimSDKListener(onConnectFailed: (int code, String error) {// 连接失败的回调函数// code 错误码// error 错误信息},onConnectSuccess: () {// SDK 已经成功连接到腾讯云服务器},onConnecting: () {// SDK 正在连接到腾讯云服务器},onKickedOffline: () {// 当前用户被踢下线,此时可以 UI 提示用户,并再次调用 V2TIMManager 的 login() 函数重新登录。},onSelfInfoUpdated: (V2TimUserFullInfo info) {// 登录用户的资料发生了更新// info登录用户的资料},onUserSigExpired: () {// 在线时票据过期:此时您需要生成新的 userSig 并再次调用 V2TIMManager 的 login() 函数重新登录。},onUserStatusChanged: (List<V2TimUserStatus> userStatusList) {//用户状态变更通知//userStatusList 用户状态变化的用户列表//收到通知的情况:订阅过的用户发生了状态变更(包括在线状态和自定义状态),会触发该回调//在 IM 控制台打开了好友状态通知开关,即使未主动订阅,当好友状态发生变更时,也会触发该回调//同一个账号多设备登录,当其中一台设备修改了自定义状态,所有设备都会收到该回调},);// 3.初始化SDKV2TimValueCallback<bool> initSDKRes =await TencentImSDKPlugin.v2TIMManager.initSDK(sdkAppID: sdkAppID, // SDKAppIDloglevel: LogLevelEnum.V2TIM_LOG_ALL, // 日志登记等级listener: sdkListener, // 事件监听器);if (initSDKRes.code == 0) {//初始化成功}
反初始化
普通情况下,如果您的应用生命周期跟 IM SDK 生命周期一致,退出应用前可以不进行反初始化。
但有些特殊场景,例如您只在进入特定界面后才初始化 IM SDK,退出界面后不再使用,可以对 IM SDK 进行反初始化。
示例代码如下:
// 反初始化 SDKTencentImSDKPlugin.v2TIMManager.unInitSDK();
常见问题
1. 在调用登录等其他接口时,发生错误,返回错误码是 6013 和错误描述是 "not initialized" 的信息。
在使用 IM SDK 登录、消息、群组、会话、关系链和资料、信令的功能前,必须先进行初始化。