单例对象

初始化 SDK

重要

整个 App 生命周期内，原则上 SDK 只能初始化一次
SDK 允许调用该方法重复初始化 SDK，但是我们不建议这么做
因为 SDK 重复初始化之后，之前的连接、监听等均会失效，需要将初始化后的操作重新做一遍，如重新连接，并重新设置各种监听
Copy

示例代码

// 在 UIAbility 中获取 context
let context = this.context
let initOption = new InitOption();
let appKey = "从融云后台获取的 appKey";
IMEngine.getInstance().init(context, appKey, initOption);
Copy

获取 SDK 版本号

示例代码

let ver = IMEngine.getInstance().getVersion();
Copy

上报 APP 版本信息，服务端支持按上报的 App 版本处理自定义消息的推送内容

示例代码

let appVersion = "1.0.0";
IMEngine.getInstance().setAppVersion(appVersion);
Copy

上设置断线重连时是否踢出重连设备。

说明

用户没有开通多设备登录功能的前提下，同一个账号在一台新设备上登录的时候，会把这个账号在之前登录的设备上踢出。
由于 SDK 有断线重连功能，存在下面情况： 用户在 A 设备登录，A 设备网络不稳定，没有连接成功，SDK 启动重连机制。 用户此时又在 B 设备登录，B 设备连接成功。 A
设备网络稳定之后，用户在 A 设备连接成功，B 设备被踢出。 这个接口就是为这种情况加的。
Copy

示例代码

let kickEnable = true;
IMEngine.getInstance().setReconnectKickEnable(kickEnable);
Copy

设置鸿蒙推送 token

说明

1. SDK 初始化之前设置：SDK 会将推送 token 缓存，连接成功后上报
2. SDK 初始化之后连接之前设置：连接成功后 SDK 自动上报
3. SDK 连接成功后设置：SDK 立即上报
Copy

示例代码

import { pushService } from '@kit.PushKit';

pushService.getToken((error: BusinessError, token: string) => {
 if (token) {
   IMEngine.getInstance().setPushToken(token);
 }
});
Copy

设置数据库状态监听

说明

数据库打开的时机：参考 DatabaseStatusListener.onDatabaseStatusChange()
Copy

示例代码

IMEngine.getInstance().setDatabaseStatusListener((status: DatabaseStatus) => {
 hilog.info(0x0000, 'IM-App', 'setDatabaseStatusListener onChanged status:%{public}d', status);
});
Copy

增加数据库状态监听

说明

数据库打开的时机：参考 DatabaseStatusListener.onDatabaseStatusChange()
Copy

示例代码

let dbListener: DatabaseStatusListener = {
 onDatabaseStatusChange: (status: DatabaseStatus): void => {
   // status 为具体的数据库状态
 }
}
IMEngine.getInstance().addDatabaseStatusListener(dbListener);
Copy

移除数据库状态监听

示例代码

IMEngine.getInstance().removeDatabaseStatusListener(dbListener);
Copy

设置控制台日志级别

说明

例如：填入 LogLevel.None ，SDK 将不再控制台输出日志
例如：填入 LogLevel.Warn ，SDK 将会在控制台输出 Warn 和 Error 的日志
Copy

示例代码

IMEngine.getInstance().setLogLevel(LogLevel.Info)
Copy

连接 IM

说明

调用该接口，SDK 会在 timeLimit 秒内尝试重连，直到出现下面三种情况之一
第一、连接成功，回调 IConnectResult.code === EngineError.Success
第二、超时，回调 IConnectResult.code === EngineError.ConnectionTimeout，需要手动调用该接口继续连接
第三、出现 SDK 无法处理的错误，回调 IConnectResult.code 为具体的错误码

常见的错误如下：
ClientNotInit ：SDK 没有初始化，请先调用 init 接口

NaviRespTokenIncorrect ：检查一下 APP 使用的 appKey 和 APP Server 使用的 appKey 是否相同
ConnectTokenIncorrect ：检查一下 APP 使用的 appKey 和 APP Server 使用的 appKey 是否相同

ConnectOneTimePasswordUsed ：重新请求 Token
ConnectPlatformError ：重新请求 Token
ConnectTokenExpired ：重新请求 Token

ConnectAppBlockOrDelete ： 给用户提示 AppKey 已经封禁或删除

ConnectUserBlocked ：给用户提示被封禁
DisconnectUserKicked ：给用户提示被提掉线
DisconnectUserBlocked ：给用户提示被封禁
ConnectUserDeleteAccount ：给用户提示已销号
Copy

示例代码

let token = "IMToken";
let timeout = 5;
IMEngine.getInstance().connect(token, timeout).then(result => {
 if (EngineError.Success === result.code) {
   // 连接成功
   let userId = result.userId;
   return;
 }
 if (EngineError.ConnectTokenExpired === result.code) {
   // Token 过期，从 APP 服务请求新 token，获取到新 token 后重新 connect()
 } else if (EngineError.ConnectionTimeout === result.code) {
   // 连接超时，弹出提示，可以引导用户等待网络正常的时候再次点击进行连接
 } else {
   //其它业务错误码，请根据相应的错误码作出对应处理。
 }
});
Copy

设置连接状态监听

说明

每个连接状态都有详细的描述和处理意见，参考 ConnectionStatusListener.onConnectionStatusChanged()
Copy

示例代码

IMEngine.getInstance().setConnectionStatusListener((status: ConnectionStatus) => {
 // status 为具体的连接状态
});
Copy

增加连接监听。每个连接状态都有详细的描述和处理意见

说明

每个连接状态都有详细的描述和处理意见，参考 ConnectionStatusListener.onConnectionStatusChanged()
Copy

示例代码

 let statusListener: ConnectionStatusListener = {
   onConnectionStatusChanged: (status: ConnectionStatus): void => {
     // status 为具体的连接状态
   }
 }
 IMEngine.getInstance().addConnectionStatusListener(statusListener);
Copy

移除连接监听

示例代码

IMEngine.getInstance().removeConnectionStatusListener(statusListener);
Copy

获取当前连接状态

示例代码

 IMEngine.getInstance().getCurrentConnectionStatus().then(result => {
   if (EngineError.Success !== result.code) {
     // 获取当前连接状态失败
     return;
   }
   if (!result.data) {
     // 获取的当前连接状态为空
     return;
   }
   let status = result.data as ConnectionStatus;
 });
Copy

获取当前用户 ID

示例代码

 IMEngine.getInstance().getCurrentUserId().then(result => {
   if (EngineError.Success !== result.code) {
     // 获取用户 ID 失败
     return;
   }
   if (!result.data) {
     // 获取的用户 ID 为空
     return;
   }
   let userId = result.data as string;
 });
Copy

断开连接

示例代码

let isReceivePush = true;
IMEngine.getInstance().disconnect(isReceivePush);
Copy

设置消息接收监听

示例代码

 IMEngine.getInstance().setMessageReceivedListener((message: Message, info: ReceivedInfo) => {
   //  针对接收离线消息时，服务端会将 200 条消息打成一个包发到客户端，客户端对这包数据进行解析。该参数表示每个数据包数据逐条上抛后，还剩余的条数
   let left = info.left;
   // 消息是否离线消息
   let isOffline = info.isOffline;
   // 是否在服务端还存在未下发的消息包
   let hasPackage = info.hasPackage;
 });
Copy

添加消息接收监听，可以添加多个监听

示例代码

 let messageReceiveListener: MessageReceivedListener = {
   onMessageReceived: (message: Message, info: ReceivedInfo): void => {
     // 收到了单条消息
   },
   onOfflineMessageSyncCompleted: (): void => {
     // 离线消息已全部拉取完成
   }
 };
 IMEngine.getInstance().addMessageReceivedListener(messageReceiveListener);
Copy

移除消息接收监听

示例代码

IMEngine.getInstance().removeMessageReceivedListener(messageReceiveListener);
Copy

设置消息撤回监听，撤回了之后，原始消息会变成 RecallNotificationMessage 消息

示例代码

IMEngine.getInstance().setMessageRecalledListener((message: Message, recallMessage: RecallNotificationMessage) => {

});
Copy

增加消息撤回监听。撤回了之后，原始消息会变成 RecallNotificationMessage 消息

示例代码

 let recalledListener : MessageRecalledListener = {
   onMessageRecalled: (message: Message, recallMessage: RecallNotificationMessage): void => {
     // 消息撤回
   }
 }
 IMEngine.getInstance().addMessageRecalledListener(recalledListener);
Copy

移除消息撤回监听

示例代码

IMEngine.getInstance().removeMessageRecalledListener(recalledListener);
Copy

设置消息敏感词拦截监听

示例代码

 IMEngine.getInstance().setMessageBlockedListener((blockInfo: MessageBlockInfo) => {

 });
Copy

增加消息敏感词拦截监听

示例代码

 let blockedListener : MessageBlockedListener = {
   onMessageBlocked: (blockInfo: MessageBlockInfo): void => {

   }
 }
 IMEngine.getInstance().addMessageBlockedListener(blockedListener);
Copy

移除消息敏感词拦截监听

示例代码

IMEngine.getInstance().removeMessageBlockedListener(blockedListener);
Copy

发送消息

说明

如果遇到 DatabaseNotOpened = 34301 ，原因是在 IM 连接成功前发送了消息
IM 连接成功后 SDK 才会打开对应用户的消息数据库
Copy

示例代码

 let conId = new ConversationIdentifier();
 conId.conversationType = ConversationType.Private;
 conId.targetId = "会话 id";

 let textMsg = new TextMessage();
 textMsg.content = "文本消息的内容";

 let msg = new Message(conId, textMsg);

 let option: ISendMsgOption = {};

 IMEngine.getInstance().sendMessage(msg, option, (msg: Message) => {
   // 消息入库回调
 }).then(result => {
   if (EngineError.Success !== result.code) {
     // 发送消息失败
     return;
   }
   if (!result.data) {
     // 消息数据为空
     return;
   }
   let msg = result.data as Message;
 })
Copy

发送媒体消息

说明

如果遇到 DatabaseNotOpened = 34301 ，原因是在 IM 连接成功前发送了消息
IM 连接成功后 SDK 才会打开对应用户的消息数据库
Copy

示例代码

 let conId = new ConversationIdentifier();
 conId.conversationType = ConversationType.Private;
 conId.targetId = "会话 id";

 let imgMsg = new ImageMessage();
 // 使用沙盒路径创建图片消息。系统路径的图片 SDK 无法访问（例如相册的图片路径 SDK 就无法访问）
 imgMsg.localPath = localPath;

 let msg = new Message(conId, imgMsg);

 let option: ISendMsgOption = {};

 IMEngine.getInstance().sendMediaMessage(msg, option, (msg: Message) => {
   // 消息保存到数据库
 }, (msg: Message, progress: number) => {
   // 媒体上传进度 [1 ~ 100]
 }).then(result => {
   if (EngineError.Success !== result.code) {
     //发送消息失败
     return;
   }
   if (!result.data) {
     // 消息为空
     return;
   }
   let msg = result.data as Message;
 })
Copy

发送普通定向消息

说明

此方法用于在群组中发送消息给其中的部分用户，其它用户不会收到这条消息。
如果遇到 DatabaseNotOpened = 34301 ，原因是在 IM 连接成功前发送了消息
IM 连接成功后 SDK 才会打开对应用户的消息数据库
Copy

示例代码

 let conId = new ConversationIdentifier();
 conId.conversationType = ConversationType.Private;
 conId.targetId = "会话 id";

 let textMsg = new TextMessage();
 textMsg.content = "文本消息的内容";

 let msg = new Message(conId, textMsg);

 let option: ISendMsgOption = {};

 // 填入实际的用户 id
 let userIdArray = ["userId1", "userId2"];

 IMEngine.getInstance().sendDirectionalMessage(msg, option, userIdArray, (msg: Message) => {
     // 消息入库回调
   }).then(result => {
     if (EngineError.Success !== result.code) {
       // 发送消息失败
       return;
     }
     if (!result.data) {
       // 消息数据为空
       return;
     }
     let msg = result.data as Message;
 })
Copy

发送媒体定向消息

说明

此方法用于在群组中发送消息给其中的部分用户，其它用户不会收到这条消息。
如果遇到 DatabaseNotOpened = 34301 ，原因是在 IM 连接成功前发送了消息
IM 连接成功后 SDK 才会打开对应用户的消息数据库
Copy

示例代码

 let conId = new ConversationIdentifier();
 conId.conversationType = ConversationType.Private;
 conId.targetId = "会话 id";

 let imgMsg = new ImageMessage();
 // 使用沙盒路径创建图片消息。系统路径的图片 SDK 无法访问（例如相册的图片路径 SDK 就无法访问）
 imgMsg.localPath = localPath;

 let msg = new Message(conId, imgMsg);

 let option: ISendMsgOption = {};

 // 填入实际的用户 id
 let userIdArray = ["userId1", "userId2"];

 IMEngine.getInstance().sendDirectionalMediaMessage(msg, option, userIdArray, (msg: Message) => {
   // 消息保存到数据库
 }, (msg: Message, progress: number) => {
   // 媒体上传进度 [1 ~ 100]
 }).then(result => {
   if (EngineError.Success !== result.code) {
     //发送消息失败
     return;
   }
   if (!result.data) {
     // 消息为空
     return;
   }
   let msg = result.data as Message;
 })
Copy

下载媒体消息

示例代码

 let messageId = 234;
 IMEngine.getInstance().downloadMediaMessage(messageId).then(result => {
   if (EngineError.Success === result.code) {
     // 本地路径
     let localPath = result.data as string;
   }
 });
Copy

下载媒体消息，含下载进度

示例代码

 let messageId = 123;
 IMEngine.getInstance().downloadMediaMessageWithProgress(messageId, (messageId: number, progress: number) => {
   // 下载进度，取值范围 [0 , 100]
 }).then(result => {
   if (EngineError.Success === result.code) {
     // 本地路径
     let localPath = result.data as string;
   }
 });
Copy

取消下载媒体消息，配合 downloadMediaMessageWithProgress 方法

示例代码

 let messageId = 123;
 IMEngine.getInstance().cancelDownloadMediaMessage(messageId).then(result => {
   if (EngineError.Success === result.code) {
     // 下载取消成功，此时 downloadMediaMessageWithProgress 会返回 EngineError.RequestCanceled
   } else {
     // 下载取消失败
   }
 });
Copy

下载文件（带下载进度）

说明

如果是下载媒体消息，请调用 downloadMediaMessageWithProgress 方法，下载成功 SDK 会更新媒体消息的本地路径
不是媒体消息的媒体文件需要下载时，才调用 downloadFileWithProgress

会将 file_name 最后一个 . 之前的特殊替换为下划线。如 abc@123.png 会被替换为 abc_123.png。
如果多次请求 file_name 相同，后一次下载会加入序号，如 abc.png，abc(1).png，abc(2).png。

Copy

示例代码

 let remoteUrl = "https://expamle.com/1.jpg";
 let fileName = "1.jpg";

 IMEngine.getInstance().downloadFileWithProgress(remoteUrl, fileName, (uniqueId: number) => {
   // 开始下载，下载唯一标识 uniqueId
 }, (uniqueId: number, progress: number) => {
   // 下载进度
 }).then(result => {
   if (EngineError.Success !== result.code) {
     // 下载失败
     return;
   }
   if (!result.data) {
     // 下载的本地路径为空
     return;
   }
   // 本地路径
   let localPath = result.data as string;
 });
Copy

取消下载文件，配合 downloadFileWithProgress 方法

示例代码

 // uniqueId 必须是调用 downloadFileWithProgress 时由 SDK 生成的，此处进行了简写
 let uniqueId = 1234;

 IMEngine.getInstance().cancelDownloadFile(uniqueId).then(result => {
   if (EngineError.Success !== result.code) {
     // 取消下载失败
     return;
   }
   // 取消下载成功，此时 downloadFileWithProgress 会返回 EngineError.RequestCanceled
 })
Copy

撤回消息

示例代码

 // 必须用发送成功的消息，此处进行了简写
 let message : Message;
 IMEngine.getInstance().recallMessage(message).then(result => {
   if (EngineError.Success !== result.code) {
     // 消息撤回失败
     return;
   }
   if (!result.data) {
     // 撤回小灰条消息为空
     return;
   }
   // 撤回小灰条消息
   let recallNtfMsg = result.data as RecallNotificationMessage;
 })
Copy

注册自定义消息，初始化之后，连接之前调用

自定义消息示例代码

import { JsonConverter, MessageContent, MessageFlag, MessageTag } from '@rongcloud/imlib';
import List from '@ohos.util.List';

const CustomOrderMessageObjectName = "App:OrderMsg";
const CustomOrderMessageFlag = MessageFlag.Count;


// 1. 继承 MessageContent 并实现 MessageTag 注解
&#64MessageTag(CustomOrderMessageObjectName,CustomOrderMessageFlag)
class CustomOrderMessage extends MessageContent {
  // 2. 按需增加属性
  id: string = ""; // 订单 ID
  name: string = ""; // 订单名称
  price: number = 0; // 订单价格

  // 3. 必须声明无参的构造方法，因为注册自定义消息时候，只能用无参构造方法
  constructor() {
    super();
  }

  // 4. 将消息对象转为 JSON 字符串
  encode(): string {
    // 4.1 将基类的数据保存到 map 中
    let map = super.encodeBaseData();

    // 4.2 将本类的独有属性放到 map 中
    // 说明：ts 的 map 必须指定 kv 的类型，所以存多种类型数据，需要转为 Object
    if (this.id) {
      map.set("id", this.id as Object);
    }
    if (this.name) {
      map.set("name", this.name as Object);
    }
    map.set("price", this.price as Object);

    // 4.3 将 map 转为 字符串
    return JsonConverter.stringifyFromHashMap(map);
  }

  // 5. 将字符串转为消息对象
  decode(contentJson: string): void {
    // 5.1 将字符串转为 map
    let map = JsonConverter.parseToHashMap(contentJson);
    // 5.2 将基类的数据解析出来
    super.decodeBaseData(map);

    // 5.3 将本类的独有属性解析
    // 说明：需要将 Object 转为对应的数据类型
    if (map.get("id")) {
      this.id = map.get("id") as string;
    }
    if (map.get("name")) {
      this.name = map.get("name") as string;
    }
    if (map.get("price")) {
      this.price = map.get("price") as number;
    }
  }

  // 6. 将当前类名返回：该方法的作用是防止代码混淆或者压缩后无法获取正常的类名
  // 直接写字符串可能会出现拼写错误的情况，所以此处建议直接使用 类名.name
  getClassName(): string {
    return CustomOrderMessage.name;
  }


  // 7. 返回搜索字段
  // 1) 不实现该方法，该类消息无法被搜索
  // 2) 实现该方法，返回 null 或者 List 长度为 0，无法被搜索
  // 3) 实现该方法， List 里面的 空字符串 和 null 会被忽略
  // 4) List 中必须包含有效的字符串才能被搜索到
  getSearchableWord(): List<string> | null {
   if (!this.name) {
     return null;
   }
   let list = new List<string>();
   list.add(this.name);
   return list;
  }
}

export { CustomOrderMessage, CustomOrderMessageObjectName }
Copy

注册自定义消息示例代码

let clazzList: List<MessageContentConstructor> = new List();
clazzList.add(CustomOrderMessage);
IMEngine.getInstance().registerMessageType(clazzList);
Copy

获取 SDK 中所有的消息 objectName 和存储标识的映射关系

注意事项

1. 映射关系集合包含 内置消息 和 自定义消息
2. 必须在所有自定义消息注册完成之后再调用该方法，否则会导致无法正确获取自定义消息的映射关系
3. 不要频繁调用该方法：建议 app 调用该方法之后， app 自行保存整个集合
Copy

其他平台说明

iOS 通过 RCMessagePersistentCompatible.persistentFlag 获取消息存储标识
Android 通过 getClass().getAnnotation(MessageTag.class) 获取消息存储标识
鸿蒙需要通过本方法获取
Copy

如何获取 objectName？

1. 发送消息时需要手动构造指定的消息体，可以直接获取到 objectName：例如创建文本消息时一定知道是文本消息的 objectName
2. 接收消息时通过 Message 对象获取：Message.objectName
3. 读取会话时通过 Conversation 对象获取：Conversation.objectName
Copy

示例代码

let hashMap = IMEngine.getInstance().getMessageTypeMap();
Copy

消息批量入库（多用于数据迁移）

Message 下列属性会被入库，其他属性会被抛弃：

conversationType   会话类型
targetId           会话 ID
channelId          所属会话的业务标识，长度限制 20 字符
direction          消息方向
senderId           发送者 ID
receivedStatus     接收状态
sentStatus         发送状态
sentTime           发送时间
content            消息内容
objectName         消息类型，设置 content 的时候 SDK 会自动赋值对应的 objectName
messageUid         服务端生产的消息唯一 ID，如要携带该字段需要保证入库后是唯一的
extra              扩展信息
Copy

示例代码

 // 必须是有效的消息集合，此处进行了简写
 let msgList : List<Message> ;
 IMEngine.getInstance().batchInsertMessage(msgList).then(result => {
   if (EngineError.Success !== result.code) {
     // 批量入库失败
     return;
   }
   // 批量入库成功
 });
Copy

单条消息入库

Message 下列属性会被入库，其他属性会被抛弃：

conversationType   会话类型
targetId           会话 ID
direction          消息方向，默认为发送
senderId           发送者 ID
receivedStatus     接收状态，默认为未读
sentStatus         发送状态，默认为发送失败
sentTime           发送时间
content            消息内容
objectName         消息类型，设置 content 的时候 SDK 会自动赋值对应的 objectName
messageUid         服务端生产的消息唯一 ID，如要携带该字段需要保证入库后是唯一的
extra              扩展信息
Copy

示例代码

 // 必须是有效的消息对象，此处进行了简写
 let msg : Message;

 IMEngine.getInstance().insertMessage(msg).then(result => {
   if (EngineError.Success !== result.code) {
     // 入库失败
     return;
   }
   if (!result.data) {
     // 入库的消息体为空
     return;
   }
   // 入库成功的消息，含有效的 messageId
   let dbMsg = result.data as Message;
 });
Copy

通过 messageId 获取单条消息

示例代码

 let messageId = 123;
 IMEngine.getInstance().getMessageById(messageId).then(result => {
   if (EngineError.Success !== result.code) {
     // 获取本地消息失败
     return;
   }
   if (!result.data) {
     // 获取本地消息为空
     return;
   }
   // 获取到有效的本地消息
   let dbMsg = result.data as Message;
 })
Copy

通过 messageUid 获取单条消息

示例代码

 let messageUid = "CH2C-A072-OGM5-E3HL";
 IMEngine.getInstance().getMessageByUid(messageUid).then(result => {
   if (EngineError.Success !== result.code) {
     // 获取本地消息失败
     return;
   }
   if (!result.data) {
     // 获取本地消息为空
     return;
   }
   // 获取到有效的本地消息
   let dbMsg = result.data as Message;
 })
Copy

获取批量本地消息，基于 messageId 获取

示例代码

 let conId = new ConversationIdentifier();
 conId.conversationType = ConversationType.Private;
 conId.targetId = "TestTargetId"; // 按需填写实际的会话 id

 let option: IGetLocalMsgByIdOption = {
   messageId: 100,
   beforeCount: 5,
   afterCount: 5
 }

 IMEngine.getInstance().getHistoryMessagesById(conId, option).then(result => {
   if (EngineError.Success !== result.code) {
     // 获取消息失败
     return;
   }
   if (!result.data) {
     // 消息不存在
     return;
   }
   // 消息体集合
   let msgList = result.data as List<Message>;
 });
Copy

获取批量本地消息，基于 time 获取

示例代码

 let conId = new ConversationIdentifier();
 conId.conversationType = ConversationType.Private;
 conId.targetId = "TestTargetId"; // 按需填写实际的会话 id

 let option: IGetLocalMsgByTimeOption = {
   time: Date.now(),
   beforeCount: 5,
   afterCount: 5
 };

 IMEngine.getInstance().getHistoryMessagesByTime(conId, option).then(result => {
   if (EngineError.Success !== result.code) {
     // 获取消息失败
     return;
   }
   if (!result.data) {
     // 消息不存在
     return;
   }
   // 消息列表
   let msgList = result.data as List<Message>;
 });
Copy