终端 SDK 相关问题

最近更新时间:2025-09-24 15:05:52

我的收藏

TUIKit 源码是否支持 Androidx?

TUIKit 最新源码已经支持 Androidx。

出现 6013 SDK 未初始化错误?

如果出现 6013 SDK 未初始化错误,您可以尝试以下方式排查:
1. 查看是否没有登录成功就进行收发消息等其他操作;
2. 查看是否登录时被其它终端踢掉,IM SDK 默认一个账号仅能在一个终端上登录。处理方式请参考 多终端同时登录 文档;
3. Android 请关注库文件是否未能全部加载,或是使用过程中被系统回收。
4. 当开发者并没有调用 SDK initSDK 接口初始化 IM 时,也会出现此报错问题。

发送表情,消息列表显示为空、或者乱码?

即时通信 IM 不提供表情包,具体的解析需要自己对齐。
表情使用有两种方式:
一种是使用 V2TIMFaceElem 中的 index,标识表情的索引,例如 Android 和 iOS 两端都有同一套表情图,索引2为笑脸,index=2 就表示笑脸,两端发送和接收都显示同一张索引表情图片即可。
另一种是使用 V2TIMFaceElem 中的 data,例如表情图片是由字符串命名,smile 表示笑脸,可在 data 中存储 smile,iOS 和 Android 两端都通过 data 作为 key 找到对应表情图片进行显示。
另外也可以两个字段都使用,如 data 表示哪一套表情,index 表示这套表情的哪个索引,可以实现类似 QQ 的多种不同表情效果。甚至可以在 data 数据中存储更为复杂的数据结构,只要多端解析规则一致即可。

翻译 IM 消息,怎么剔除表情和 @ 消息?

1. 先把输入的文本过滤一遍,提取出不需要翻译的表情或者 at 信息并缓存起来,把需要翻译的设置给接口。
2. 等翻译结果返回后,再把缓存的不需要的翻译的表情或者 at 信息一起组合起来

有时进行操作时返回错误码:10002?

在需要进行服务端验证的操作时,如果网络异常、超时或者票据切换失败,就会返回此状态码,遇到此状态码时稍后重试即可。

收发消息时,收到错误码 6200 或 6201?

返回此状态码时,是客户端在网络离线、超时或无网络访问时出现,6200 的定义为请求时没有网络,6201 的定义为响应时没有网络,遇到此状态码时,请检查网络或等待网络恢复后重试。

收发消息时返回错误码:20003?

请检查用户账号(UserID)是否已在腾讯云导入,当 UserID 无效或 UserID 未导入腾讯即时通信 IM 时,会返回此错误码。

语音消息播放语音时返回错误码:6010?

通常情况是语音消息超过了漫游保存有效期,请求失败导致,可 延长漫游消息时间 或获取语音文件到本地播放(已过期的文件无法恢复)。但不同版本的 SDK 支持延长历史消息存储时长的消息类型不同,详情请参见 消息存储

账号鉴权时返回错误码 70001 或 70003 或 70009 或 70013?

这些状态码对应的原因是 UserID 与 UserSig 不匹配,请检查 UserID 及 UserSig 的有效性。其中,70001 定义为 UserSig 已过期,70003 定义为 UserSig 被截断导致校验失败,70009 定义为 UserSig 验证失败(可能是因为生成 UserSig 时混用了其他 SDKAppID 的密钥或私钥导致),70013 定义为 UserID 不匹配。

Web 端使用 IM SDK 时返回错误码-2或-5?

-2:Web 端请求服务器失败,通常为网络问题,Web 端使用 HTTP Long Polling 方式向服务端请求,网络存在问题时会返回此状态码,请检查网络或重试。
-5:登录操作未完成,SDK 未获取到服务器返回的 a2key 和 tinyID 时,直接调用其它接口会出现“tinyid或a2为空”的错误提示信息和-5的错误码。

在 armeabi 平台上 SDK 报"java.lang.UnsatisfiedLinkError: No implementation found for"错误该如何处理?

拷贝 imsdk 的 aar 里面的 jni/armeabi-v7a/libImSDK.so 到源码工程的 src/main/jniLibs/armeabi 目录里,并在 build.gradle 中加载即可。

上架 App Store 时,出现 x86_64, i386 架构错误该如何解决?

该问题是由于 App Store 不支持 x86_64, i386 架构引起的,具体解决方法如下:
1. 清空项目编译缓存: 选择Product>clean,按住Alt变成 clean build Folder...,等待操作完成。
2. 剔除 App Store 不支持的 x86_64 和 i386 架构: a. 选择TARGETS>Build Phases。 b. 单击加号,选择New Run Script Phase。 c. 添加如下代码:
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and

# removes unused architectures.

find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done

3. 重新打包上传。

IM 各端 Demo/TUIKit 工程中演示用的表情包,开发者是否可以直接使用?

为了尊重版权,IM Demo/TUIKit 工程中默认不包含大表情元素切图。在正式上线商用前,请您替换为自己设计或拥有版权的其他表情包。请注意,下图所示的默认小黄脸表情包版权属于腾讯云,您可以通过升级至 IM 企业版套餐 免费使用该表情包。




会话列表同步规则?

getConversationList(拉取会话列表) 是异步拉取本地缓存的会话列表数据
1. 第一次登录成功后,IM SDK 内部会去同步服务端漫游会话和未读消息(此时本地暂无会话缓存数据)。
2. 首次登录,在漫游会话还没同步完成之前,调用 getConversationList 接口拉取本地会话列表,会返回空数据。
3. 会话同步完成后,SDK 会通过 V2TIMConversationListener -> onSyncServerFinish 回调告知上层(上层可以在收到此回调再去拉取会话)
4. 会话同步完成,对于本地缓存的会话有变更,也会通过V2TIMConversationListener ->( onNewConversation | onConversationChanged) 回调告知上层。

应用切后台或息屏情况下客户端 IM SDK 会一直处于连接状态吗?

不会,切后台或息屏都有可能导致 IM 连接断开。IM 只有长连接保活,没有进程保活。主要原因是手机厂商对于应用处于后台运行的限制策略越来越严格。
当 App 应用切后台或处于前台息屏,由于手机操作系统回收机制的策略原因,应用进程被挂起导致 IM 连接断开。不过应用重新切回前台,只要进程没有改变,IM SDK 感知到网络变化会自动重连(推荐:前台可配合调用 doForeground 接口,可主动触发重连)。
SDK 重连动作会触发:V2TIMSDKListener-> onConnecting、onConnectSuccess、onConnectFailed回调,告知上层当前IM连接状态。






Android 端 UIKit 接入,添加自定义消息,不需要显示默认边距,该如何操作?

方法一:在不需要显示内边距的 Holder -> layoutVariableViews 函数中,添加以下代码:
msgArea.setPaddingRelative(0, 0, 0, 0);
reactionArea.setPaddingRelative(0,0,0,0);

方法二:layoutVariableViews 函数最底部调用下面两个方法:
setMessageBubbleBackground(null);
setMessageBubbleZeroPadding();

IM SDK 是什么样的日志缓存策略?

IM SDK 的日志模块是使用了微信 MARS 的 Xlog,XLog使用流式方式对单行日志进行压缩,压缩加密后写入作为 log 中间 buffer 的 mmap 中。使用 Xlog 方案,除非 io 损坏或者磁盘没有可用空间,基本可以保证不会丢失任何一行日志。
1. 日志先写内存映射文件.mmap3。
2. 每15分钟从 mmap3 flush 一次到本地xlog文件。
3. 如果内容大于100kB,直接 Flush。
4. 结束进程重新登录也会直接 Flush。
5. 本地缓存的日志文件只会保存7天。

调用 IM SDK API 接口,报 6014 错误,请问如何优化?

6014 是比较常见的问题,例如:登录失败、被踢、主动退出登录,导致当前 IM 处于未登录状态,后续调用 IM SDK 接口未重新登录都会报 6014 错误。
我们的建议是:在上层做下兜底逻辑,例如:将 IM 所有使用的接口error回调统一处理,如遇到 6014 报错统一做下 login 操作成功后再请求一次,让用户无感知。
SDK 也有提供以下两个 API,用于 login 接口调用的判重处理,防止重复调用:
1. getLoginStatus():获取当前登录状态,如果登录状态为已登录登录中,则上层无需调用 login 接口重复登录,仅无登录状态下调用即可(特例:如果是 UserSig 过期,那么可在 UserSig 过期回调内做登录操作,无需判断登录状态)。
2. getLoginUser():获取当前已登录的 UserID,如果当前已登录的 UserID 与需要业务层登录的 UserID 不一致,可重新登录,否则过滤不处理。

IM SDK 主动获取各类资料的缓存时长是否有限制?

主动获取群资料:默认1小时缓存时长。
主动获取群成员:默认1小时缓存时长。
主动获取用户资料:默认10分钟缓存时长。

IM SDK 重连策略是怎样的?

网络状态发生变更时,IM SDK会自动重连。重连最多重试 6 次,最长要一分钟左右;如果 3 分钟左右 SDK 多种重连方式均失败则暂停继续重连,主动调用 API 接口或感知网络变化会再次触发重连。
IM SDK 有自己的一套长连接保活的逻辑,接入层一般不需要关注重连动作,正常调用接口就好。

为什么 github 里下载的 Demo 的 TUI 组件代码和 pod ‘TUIXXX’ 集成的代码不一样?

github 里下载的 Demo 先 pod update,再对比看看。

冷启动 App 后首次拉取好友申请列表,有一定概率会报错提示未登录,打印登录状态是登录中,是什么问题?

除获取会话列表、拉取历史消息这两个接口以外,SDK 的各项功能接口必须在登录成功后才能调用。

IM 运行报冲突:Multiple commands produce '/Users/apple/Library/Developer/Xcode/DerivedData/xxx/Build/Products/Debug-iphonesimulator/xxx.app/Frameworks/ImSDK_Plus.framework',该如何解决?

导致报冲突的原因通常是集成了两个或者以上的 IM SDK,只保留一个即可,常见情形:
1. 客户单独集成 TXIMSDK_Plus_iOS 后,又集成 TUI 组件,通过 TUI 组件又集成了 IM SDK,编译报冲突。
解决:这种情况可以将单独集成的 TXIMSDK_Plus_iOS 去掉。
2. 之前集成了 TUIChatTUIConversationTUICore 等非音视频相关的 TUI 组件,通过依赖集成进入到 TXIMSDK_Plus_iOS;后又集成了 TUICallKitTUIRoomKit 或者 TUILiveKit 等音视频相关的组件,这些组件依赖集成了 TXIMSDK_Plus_iOS_XCFramework,集成后编译也会报冲突。
解决:TUIChatTUIConversationTUICore 等非音视频相关的 TUI 组件使用 DevelopPods 源码集成 时,可以确认下 .podspec 文件是否依赖 IM SDK,比如 TUICore.podspec 里依赖的是 TXIMSDK_Plus_iOS 的话,可以改成 TXIMSDK_Plus_iOS_XCFramework(和音视频依赖的 IM SDK 统一),然后 pod update。
TUIChatTUIConversationTUICore 等非音视频相关的 TUI 组件直接 pod 拉下来的可以尝试 pod update 都更新至最新版本。

报错:Upload Symbols Failed: The archive did not include a dSYM for the lmSDK Plus.framework with the UUiDs[B8B90567-F276-334A-8937-4D327A49AB4C1. Ensure that the archive's dSYM folder includes a DWARF filefor lmSDK Plus.framework with the expected UUlDs.

Xcode 16 报的警告,不影响打包可先忽略。

iOS 端和 Android 端登录同一账号在线,Web 端和 iOS 端登录同一账号在线,接收通话邀请的场景下,一端挂断,另一端没有退出通话邀请界面,如何处理?

多端登录的处理需要客户调用 enableMultiDeviceAbility 接口才能开启,也需要 开通对应套餐包

报错 Error: The pod "TXIMSDK_Plus_iOS_XCFramework," required by the plugin "tencent_cloud_chat_push" requires a higher minimum iOS deployment version than the plugin's reported minimum version. To build, remove the plugin "tencent_cloud_chat_push", or contact the plugin's developers for assistance. Error running pod install. Error launching application on iPhone 16 Pro.

解决方法:
1. 打开编译器控制台,进入 iOS 目录:cd ios
2. 删除 Podfile.lockpod.lock 文件(如果存在)。
3. 执行pod更新命令:pod repo updatepod install --repo-update
4. 重新运行项目。
报错原因:
Flutter 中依赖的某个插件版本,本地 cocoapods 缓存无法检测下载,需要更新。

Flutter 使用多引擎模式,当某个引擎 detach 的时候,会把 IM SDK 的所有 channel 都释放,导致所有引擎都无法使用?

IM Flutter SDK 8.3.6498+1 版本已支持多进程。

在 iOS 上运行官网 IM Flutter Demo 报如下错误怎么办?

Swift Compiler Error(Xcode): Cannot find type 'PhoneNumber/Users/xia/.pub-cache/hosted/pub.dev/libphonenumber_plugin-.3.3/ios/Classes/SwiftLibphonenumberPlugin.swift:6:24 Could not build the application for the simulator. Error launching application on iPhone 15.

原因:iOS 项目用到了库 libphonenumber_plugin,其中依赖了 PhoneNumberKit 的最新版本。但 PhoneNumberKit 的最新版 4.0.0 是 breaking API change,其中做了改动 “renames the class PhoneNumberKit to PhoneNumberUtility“。libphonenumber_plugin 尚未针对该变动做适配,无法找到 PhoneNumberKit 而报错。
解决方法:libphonenumber_plugin 中依赖的 PhoneNumberKit 降级到旧版本 3.8.0。



Podfile 里这样改即可:


使用官方的 UI 库,长按消息底部操作栏出现 UI 显示异常?


V1 的组件是用的 material2 的样式来做的,新版 V2 是基于 material3 的。现在 Flutter 新项目默认用的是 material3。
应用一旦指定样式,全局生效,不能在组件中单独指定。
main.dart 入口处,MaterialApp 中指定 useMaterial3: false。两者在一些界面参数上有区别。
解决方案1:客户需在 MaterialApp 里指定下使用 material2 样式,不可以使用 material3 样式:useMaterial3: false
解决方案2:如果客户坚持用 material3,需从 pub 上(建议)或者 github 上下载源码,自行处理 material3 的适配。

UIKit-V1 发送视频消息,视频封面很模糊,如何解决?

体验问题,视频截图是用的第三方库 fc_native_video_thumbnail,看下是不是可以有参数调整。
Width 和 Height 改大一点,比如:从 128 改为 1280。

运行 iOS 模拟器时报错 CocoaPods not installed or not in valid state,但其实 cocoapods 安装正常,是什么原因?

按照以下顺序,重新设置一下项目:
1. flutter clean
2. flutter pub get
3. Reload Android Studio
4. flutter run
点击查看 参考文档

Flutter web 运行,一开始初始化的时候就报错:

TypeError: Cannot read properties of undefined (reading 'create')
packages/tencent_cloud_chat_sdk/web/manager/im_sdk_plugin_js.dart 134:27 initTim
packages/tencent_cloud_chat_sdk/web/manager/im_sdk_plugin_js.dart 148:14 initWebTim
packages/tencent_cloud_chat_sdk/web/manager/v2_tim_manager.dart 108:21 initSDK
packages/tencent_cloud_chat_sdk/tencent_cloud_chat_sdk_web.dart 171:26 initSDK
解决方案:点击查看 参考文档

Flutter IM Demo 怎么打 web 应用包后,在手机上运行?

点击查看 参考文档

报错 FAILURE: Build failed with an exception.

* What went wrong:
A problem occurred configuring project ':better_player_plus'.
> Could not create an instance of type com.android.build.api.variant.impl.LibraryVariantBuilderImpl.
> Namespace not specified. Specify a namespace in the module's build file. See https://d.android.com/r/tools/upgrade-assistant/set-namespace for information about setting the namespace.
解决方案1:升级插件版本(推荐)​​
修改:
pubspec.yaml:
dependencies:
better_player_plus: ^1.0.8
解决方案2:手动注入命名空间​
1. 找到插件的 Android 模块构建文件:
路径:<项目目录>/android/src/main/build.gradle
或通过缓存路径:C:\\Users\\你的用户名\\.gradle\\caches\\.../better_player_plus/../android/build.gradle
2. ​在 Android 块内添加命名空间:
android {
namespace "uz.shs.better_player_plus" // 具体值参考库的包名
// 其他配置...
}


Flutter V1 UIKit 组件接入,开启网络 URL 解析预览,某种链接内容解析出现乱码,如何解决?


解决方案1:源码引入 tencent_cloud_chat_uikit 组件。



解决方案2:link_preview_generator_for_us 引入方式改成如下方式:
link_preview_generator_for_us:
git: https://github.com/Junkmer/link_preview_generator_for_us.git




Flutter V1 UIKit 接入,怎么全局开启头像显示的圆角角度?




可通过设置 TIMUIKitConfig.defaultAvatarBorderRadius 处理。







IM Flutter Demo 选择 web 浏览器运行报如下错误:Finished with error: Failed to bind web development server: SocketException: Failed to create server socket (OS Error: Failed to start accept), address = localhost, port = 63480




解决方法1:打开 Android studio 在如下截图位置添加以下内容:--web-hostname=127.0.0.1






解决方法2:如果是通过 terminal 命令工具运行,通过如下方式:flutter run -d chrome --web-hostname=127.0.0.1

Flutter Vivo 离线推送,Vivo 消息收不到,控制台工具报错 10302,如何处理?




解决方法:上线后要改成正式推送。




V1 UIKit 5.0.0 及以上版本在 Flutter 3.24.x 版本上运行不成功?

UIKit-V1 在 Flutter 3.29.0 需要最新的 5.0.0版本,依赖的 extended_text: ^15.0.0。
UIKit-V1 最新的 5.0.0版本如果要在 Flutter 3.24.3运行,需要修改 UIKit 源码依赖 extended_text: ^14.0.0。

运行 Flutter Demo 报关于 better_player_plus 错误?




better_player_plus 升级至 better_player_plus: ^1.0.8

Flutter IM SDK 接入后,在 Android、iOS、MacOS 和 Window 都运行正常,但仅在 Web 平台运行报错,报错内容如下:pub-cache/hosted/pub.dev/tencent_cloud_chat_sdk-8.6.7040/lib/native_im/bindings/native_imsdk_bindings_generated.dart:996:19: Error: 'Pointer' isn't a type. ffi.Pointer<ffi.Void>)>>('DartFindMessages');,该如何解决?

Flutter V1 UIKit Demo,选择 Android 平台运行 报如下错误:FAILURE: Build failed with an exception.

FAILURE: Build failed with an exception.
* What went wrong:
Could not open cp_settings generic class cache for settings file 'E:\\FlutterProject\\WorkProjects\\v1_demo_and_uikit\\v1_chat-demo-flutter\\android\\settings.gradle' (C:\\Users\\Administrator\\.gradle\\caches\\8.1.1\\scripts\\5f461bs4vludhoc0tr427ffwx).
> BUG! exception in phase 'semantic analysis' in source unit '_BuildScript_' Unsupported class file major version 65
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
* Get more help at https://help.gradle.org
BUILD FAILED in 1s

原因:
Unsupported class file major version 65(​​版本 65​​ 对应的是 ​​Java 21​​(Java 每个版本都有一个 class 文件版本号))。
项目使用了过旧的 Gradle 版本或系统安装了高于项目支持的 Java 版本。
解决方法:
在项目的 android/gradle.properties 文件中添加:
org.gradle.java.home=你的JDK路径(建议使用 jdk17)
示例:
Windows: org.gradle.java.home=C\\:\\\\Program Files\\\\Java\\\\jdk-11.0.20
macOS/Linux: org.gradle.java.home=/usr/lib/jvm/java-11-openjdk-amd6

HarmonyOS 切后台断连,再切回前台 SDK 重连耗时久,要如何解决?

原因:因应用切回前台时,没有主动调用 IM SDK API 接口主动触发重连,导致耗时久。
解决方法:在 HarmonyOS 工程中对应位置参考以下截图对应位置添加 SDK 两个 API,用于主动触发重连。




注册 Token 失败,报错1000900010,如何解决?

参考 鸿蒙官网错误码。提醒:使用自动签名,是不行的,需改成手动签名。

集成鸿蒙推送成功了,安卓、iOS 给鸿蒙发消息,收不到推送?

其他平台发消息代码里面,要 setHarmonyCategory