单例对象

初始化 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

获取本地时间与服务器时间的时间差。 通过当前本地时间减去此接口返回的时间，即当前服务器时间。

示例代码

IMEngine.getInstance().getDeltaTime().then(result => {
  if (EngineError.Success === result.code) {
    let deltaTime = result.data as number
  }
});
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 imgMsg = new ImageMessage();
 // 使用沙盒路径创建图片消息。系统路径的图片 SDK 无法访问（例如相册的图片路径 SDK 就无法访问）
 imgMsg.localPath = localPath;

 let msg = new Message(conId, imgMsg);

 let option: ISendMsgOption = {};

 IMEngine.getInstance().sendMediaMessageWithUploader(msg, option, (msg: Message) => {
   // 消息保存到数据库
 }, (msg: Message, progress: number) => {
   // 媒体上传进度 [1 ~ 100]
 }, (uploader: MediaMessageTransfer) => {
   // app 需要在该回调里面做上传业务，并把上传进度，上传结果通知 sdk

   // 此处 for 循环模拟上传进度。实际应该是 app 真实的上传进度
   for (let index = 1; index < 101; index++) {
     // 这里的进度取值范围必须是 [1 ~ 100]
     uploader.updateProgress(index);
   }

   // 模拟 app 是否上传媒体成功
   let appUploadSuccess = true;
   if (appUploadSuccess) {
     // app 上传媒体成功了，调用 uploader.success 通知 sdk 上传成功了，sdk 就会将该消息带着远端 url 直接发送出去
     uploader.success("https://exmaple.com/123.jpg");
   }else {
     // 如果 app 上传失败，调用 uploader.error 通知 sdk 上传失败了，sdk 会触发失败回调
     uploader.error();
   }

 }).then(result => {
   if (EngineError.Success !== result.code) {
     //发送消息失败
     return;
   }
   if (!result.data) {
     // 消息为空
     return;
   }
   let msg = result.data as Message;
 })
Copy

取消发送媒体消息下载

示例代码

 let messageId = 123;
 IMEngine.getInstance().cancelSendMediaMessage(messageId).then(result => {
   if (EngineError.Success === result.code) {
     // 取消发送媒体消息成功
   } else {
     // 取消发送媒体消息成功失败
   }
 });
Copy

发送普通定向消息

说明

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

示例代码

 let conId = new ConversationIdentifier();
 conId.conversationType = ConversationType.Group;
 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.Group;
 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

使用自定义方法下载媒体消息

示例代码

 let messageId = 234;
 IMEngine.getInstance().downloadMediaMessageWithDownloader(
   messageId,
   (messageId: number, progress: number) => {
      // 下载进度，取值范围 [0 , 100]
   },
   (downloader: MediaMessageTransfer) => {
     downloadImg(imgMsg.getPicFilePath(), new downloadListener() {
       public onSuccess(localPath: string): void {
         downloader.success(localPath);
       }
     }
   }
 ).then(result => {
   if (EngineError.Success === result.code) {
     // 本地路径
     let localPath = result.data as string;
   }
 });
Copy

暂停媒体消息下载

示例代码

 let messageId = 123;
 IMEngine.getInstance().pauseDownloadMediaMessage(messageId).then(result => {
   if (EngineError.Success === result.code) {
     // 暂停下载成功，此时 downloadMediaMessageWithProgress 会返回 EngineError.RequestPaused
   } else {
     // 暂停下载失败
   }
 });
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

下载媒体文件

示例代码

// uniqueId 是下载媒体文件任务的标识，可以用来发起下载、暂停下载和取消下载。
// 与 pauseDownloadMediaFile 和 cancelDownloadFile 中的 uniqueId 保持一致。
let uniqueId = "123"
let remoteUrl = "https://expamle.com/1.jpg";
let fileName = "1.jpg";

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

暂停下载媒体文件

示例代码

// messageId 与 downloadMediaFile 的第一个参数对应
let messageId = "123";
 IMEngine.getInstance().pauseDownloadMediaFile(messageId).then(result => {
   if (EngineError.Success === result.code) {
     // 暂停下载成功，此时 downloadMediaFile 会返回 EngineError.RequestCanceled
   } else {
     // 暂停下载失败
   }
 });
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