功能描述
拉取历史消息的 API 在类
TencentImSDKPlugin.v2TIMManager.getMessageManager()
中。除了支持单聊、群聊历史消息的拉取外,还提供了高级接口以支持按指定方向拉取、按指定起点和指定时间范围拉取。
除了支持单独拉取本地历史消息外,还支持拉取云端历史消息。
说明:
在拉取云端历史消息时,如果检测到网络异常,SDK 会返回本地存储的历史消息。
本地存储的历史消息无时间限制,但云端存储的历史消息有存储时长的限制:
体验版:免费存储 7 天,不支持延长。
专业版:免费存储 7 天,支持延长。
旗舰版:免费存储 30 天,支持延长。
说明:
延长历史消息存储时长是增值服务,您可以登录 即时通信 IM 控制台 修改相关配置,具体计费说明请参见 增值服务计费说明 。
富媒体消息(图片、文件、语音等)对应的文件存储时长,与历史消息存储时长保持一致。
拉取单聊历史消息
在网络正常的情况下会拉取最新的云端数据。如果网络出现异常,SDK 会返回本地存储的历史消息。
示例代码如下:
// 拉取单聊历史消息// 首次拉取,lastMsgID 设置为 null// 再次拉取时,lastMsgID 可以使用返回的消息列表中的最后一条消息的idTencentImSDKPlugin.v2TIMManager.getMessageManager().getC2CHistoryMessageList(userID: "userId",count: 10,lastMsgID: null,);
拉取群聊历史消息
在网络正常的情况下会拉取最新的云端数据。如果网络出现异常,SDK 会返回本地存储的历史消息。
示例代码如下:
// 拉取群聊历史消息// 首次拉取,lastMsgID 设置为 null// 再次拉取时,lastMsgID 可以使用返回的消息列表中的最后一条消息idTencentImSDKPlugin.v2TIMManager.getMessageManager().getGroupHistoryMessageList(groupID: "groupID",count: 10,lastMsgID: null,);
高级功能
高级接口
该接口除了支持普通拉取单聊、群聊历史消息外,还支持以下高级特性:
支持设置拉取消息的位置:从本地拉取、从云端拉取。
支持按照指定的方向拉取:往消息时间更老的方向拉取、往消息时间更新的方向拉取。
支持拉取本地指定的消息类型:文本、图片、语音、视频、文件、表情、群 tips 消息、合并消息、自定义消息等。
接口原型:
// 拉取单聊历史消息// 首次拉取,lastMsgID 设置为 null// 再次拉取时,lastMsgID 可以使用返回的消息列表中的最后一条消息的idV2TimValueCallback<List<V2TimMessage>> getHistoryMessageListRes =await TencentImSDKPlugin.v2TIMManager.getMessageManager().getHistoryMessageList(getType: HistoryMsgGetTypeEnum.V2TIM_GET_LOCAL_OLDER_MSG, // 拉取消息的位置及方向userID: "userID", // 用户id 拉取单聊消息,需要指定对方的 userID,此时 groupID 传空即可。groupID: "groupID", // 群组id 拉取群聊消息,需要指定群聊的 groupID,此时 userID 传空即可。count: 10, // 拉取数据数量lastMsgID: null, // 拉取起始消息id// 仅能在群聊中使用该字段。// 设置 lastMsgSeq 作为拉取的起点,返回的消息列表中包含这条消息。// 如果同时指定了 lastMsg 和 lastMsgSeq,SDK 优先使用 lastMsg。// 如果均未指定 lastMsg 和 lastMsgSeq,拉取的起点取决于是否设置 getTimeBegin。设置了,则使用设置的范围作为起点;未设置,则使用最新消息作为起点。lastMsgSeq: -1,messageTypeList: [], // 用于过滤历史信息属性,若为空则拉取所有属性信息。);if (getHistoryMessageListRes.code == 0) {//获取成功}
参数说明:
参数 | 含义 | 单聊有效 | 群聊有效 | 是否必填 | 说明 |
getType | 拉取消息的位置及方向,可以设置拉取 本地/云端 的 更老/更新 的消息 | YES | YES | YES | 当设置从云端拉取时,会将本地存储消息列表与云端存储消息列表合并后返回。如果无网络,则直接返回本地消息列表。 |
userID | 拉取指定用户的单聊历史消息 | YES | NO | NO | 拉取单聊消息,需要指定对方的 userID,此时 groupID 传空即可。 |
groupID | 拉取指定群组的群聊历史消息 | NO | YES | NO | 拉取单聊消息,需要指定群聊的 groupID,此时 userID 传空即可。 |
count | 单次拉取的消息数量 | YES | YES | YES | iOS/Android端建议设置为 20,否则可能影响拉取速度。 Web端上限为15条。 |
lastMsgID | 最后一条消息,表示从哪条消息开始拉取历史消息 | YES | YES | NO | 1. 单聊和群聊中均能使用。 2. 设置 lastMsg 作为拉取的起点,返回的消息列表中不包含这条消息。 3. 如果设置为空,则使用会话的最新一条消息作为拉取起点。 |
lastMsgSeq | 最后一条消息 seq,表示从哪条消息开始拉取历史消息 | NO | YES | NO | 1. 仅能在群聊中使用该字段。 2. 设置 lastMsgSeq 作为拉取的起点,返回的消息列表中包含这条消息。 3. 如果同时指定了 lastMsg 和 lastMsgSeq,SDK 优先使用 lastMsg。 |
分页拉取
通过
lastMsg
和 count
来实现分页。第一次拉取时 lastMsg
可以设置为空,使用消息列表中返回来最后一条消息作为下一次拉取的 lastMsg
从而拉取下一页数据。当
lastMsg
设置为空时,SDK 会默认从最新的消息开始返回。当设置
lastMsg
后,返回的消息列表不包含设置的 lastMsg
。返回的消息列表中,越新的消息越靠前。
说明:
1. 为了不影响历史消息拉取速度,建议分页时
count
设置为 20。2. 由于返回的消息列表会包含
lastMsgSeq
所对应的消息,所以在拉取群聊历史消息时,不建议使用 lastMsgSeq
来续拉。仅拉取本地消息
通过设置
getType
来实现仅拉取本地消息:getType
取值为 V2TIM_GET_LOCAL_OLDER_MSG
时,表示往时间更旧的方向,拉取本地存储的消息。getType
取值为 V2TIM_GET_LOCAL_NEWER_MSG
时,表示往时间更新的方向,拉取本地存储的消息。示例代码将演示:从最新的消息开始,往更老的方向,从本地数据库中拉取 20 条单聊消息。
TencentImSDKPlugin.v2TIMManager.getMessageManager().getHistoryMessageList(count: 20,getType: HistoryMsgGetTypeEnum.V2TIM_GET_LOCAL_OLDER_MSG,userID: "userID",);
跳转到群 @ 消息后拉取
在群聊会话中,收到群 @ 消息后,一般需要通过点击群 @ 提示条,跳转到群 @ 消息的位置,并拉取附近的消息列表用于显示。
由于群 @ 消息本身也需要显示,可以将 lastMsgSeq 设置成群 @ 消息的
sequence
,并使用 高级接口 来拉取。示例代码将演示:点击群 @ 提示后,跳转到群 @ 消息,并拉取前后各 20 条消息用于展示。
// 获取群 @ 消息对应的的 sequenceint atSequence = 1081;// 拉取群 @ 消息及之前的消息TencentImSDKPlugin.v2TIMManager.getMessageManager().getHistoryMessageList(count: 20, // 拉取 20 条getType: HistoryMsgGetTypeEnum.V2TIM_GET_CLOUD_OLDER_MSG, // 拉取比群 @ 消息更早的消息lastMsgSeq: atSequence,// 从群 @ 消息开始拉取,包括群 @ 消息groupID: "groupID" // 拉取群聊消息);// 拉取群 @ 消息之后的消息TencentImSDKPlugin.v2TIMManager.getMessageManager().getHistoryMessageList(count: 20, // 拉取 20 条getType: HistoryMsgGetTypeEnum.V2TIM_GET_CLOUD_NEWER_MSG, // 拉取比群 @ 消息更晚的消息lastMsgSeq: atSequence,// 从群 @ 消息开始拉取,包括群 @ 消息groupID: "groupID" // 拉取群聊消息);
常见问题
1. 拉历史消息时,日志中出现 "total count of request cloud message exceed max limit" 信息
SDK 目前的策略是:
1. 当 getType 设置成拉云端历史消息,且拉取 x 条消息时,SDK 会从云端拉取 x 条消息。
2. SDK 会过滤无效的消息,例如消息被删除、非当前用户关心的消息等。
3. 当云端历史消息中无效的消息过多,就会触发 SDK 多次分页拉取。
为了提供系统的稳定性和健壮性,SDK 最多触发 3 次自动分页。当超过限制后,会出现 “total count of request cloud message exceed max limit” 的日志信息。
为了尽可能的减少此类限频机制对业务层的影响,您可以使用如下措施来减少无效消息的产生:
您可以使用在线消息,也就是说在发送消息时
onlineUserOnly
字段设置为 YES/true
。如果是群聊消息,可以使用群定向消息指定消息的接收者,避免产生无效消息。
2. 拉云端历史消息时,消息 “丢失” ?
当 getType 设置成拉云端历史消息,且拉取 count 条消息时,SDK 会做如下操作:
1. SDK 先从本地拉取 count 条消息。
2. SDK 再次云端拉取 count 条消息,过滤掉被删除等无效的消息,如果不够 count 条,SDK 内部触发分页拉取。
3. 将本地和云端消息进行合并,更新消息状态等信息。
4. 从合并的消息列表中,返回 count 条消息。
一般出现消息 “丢失” 时,指的是在第 2 步中拉取的无效消息过多,导致触发了 问题 1 中的限频机制 ,从而导致实际拉取的云端消息不够。
建议按照 问题 1 中的解决方法 来处理,如果仍然无法解决,欢迎加入 QQ 群(468195767)反馈。
3. 拉取的历史消息,群名片等群成员信息没有实时更新?
SDK 会在消息产生时,更新当前的群名片、role 等群成员信息并存储在本地数据库中。
当拉取群历史消息时,会直接返回消息产生时的群成员信息,不会实时更新。