本文介绍如何创建一个 IMCloud HarmonyOS Next 项目，实现即时通讯功能。你也可以通过阅读代码，了解即时通讯的最佳实践。

• 获取 AppID 和 Token，你可以通过阅读密钥说明了解更多 Token 相关信息

• DevEco Studio 5.0.3.900+

• HarmonyOS SDK API 12 及以上。

• 运行环境 HarnomyOS NEXT 5.0.0 以上。

本步骤为如何创建一个新项目，如集成到已有项目，请直接查看集成 SDK。

1. 打开 DevEco Studio，选择 File > New > Project。

2. 选择 Application > Empty Ability，点击Next。

   
   
   

3. 填写项目信息：应用名称、包名、开发语言、支持的设备、HarmonyOS 版本，点击Finish。

   

你可以使用远程依赖的方式，或者手动下载 IMSDK 导入到项目中。若需手动下载，请联系火山引擎技术支持人员获取离线包。

远程依赖

添加仓库

在项目根目录下创建 .ohpmrc 文件并配置 OpenHarmony 三方库中心仓和火山引擎仓库地址。

registry=https://ohpm.openharmony.cn/ohpm/,https://artifact.bytedance.com/repository/byted-ohpm/

添加SDK依赖

在 entry 下的 oh-package.json5 中添加 SDK 依赖，最新版本号参看资源获取。

{
  dependencies: {
    // 将 xxx 替换成最新版本号
    "@imcloud/imsdk": "xxx",
  },
}

依赖设置完成后，需要执行 ohpm install 命令安装依赖包，依赖包会存储在工程或模块的 oh_modules 目录下:

ohpm install

手动集成

将 IMSDK 放在工程或模块 导入工程中。

{
  dependencies: {
    "@imcloud/imsdk": "file:../../imsdk.har",
  },

依赖设置完成后，需要执行 ohpm install 命令安装依赖包，依赖包会存储在工程或模块的 oh_modules 目录下:

ohpm install

初始化

在使用 IMSDK 接口功能前需要先进行初始化操作，其中 BIMSDKConfig 可配置 IMSDK 的日志监听。

let config = new BIMSDKConfig()
//1. 构造实例
this._imClient = new BIMClient(context, appID, config)
//2. 初始化，注意: 需使用 await 等待异步初始化完成
await this._imClient.init()

BIMLogLevel 日志级别含义如下

设置监听

设置 IMSDK 生命周期内重要事件的监听可以了解 IMSDK 的运行状态，数据同步状态等信息，便于开发者业务逻辑判断。

• 长链接状态监听 onConnectStatusChanged 方法回调当前长链接状态，如果长链接不可用时收发消息将会受到影响。onTokenInvalid 方法在 token 过期时会回调。

  this.imClient.addConnectListener({
    onConnectStatusChanged: (status: BIMConnectStatus): void => {
      if (status == BIMConnectStatus.BIM_CONNECT_STATUS_CONNECTED) {
        this.connectStr = "已连接"
      } else if (status == BIMConnectStatus.BIM_CONNECT_STATUS_CONNECTING) {
        this.connectStr = "连接中"
      } else {
        this.connectStr = "已断开"
      }
    },
    onTokenInvalid: (code: BIMErrorCode): void => {
    }
  })
  

登录登出

完成初始化并设置监听后，即可进入到登录流程。

• 客户端登录

客户端登录示例代码如下。登录会根据当前传入的 uid，token 鉴权，并拉取历史会话、消息等数据，同时建立长链接。

let  isSuccess = await  this.imClient.login(uid, token)

• 客户端登出

  this._imClient?.logout()
  

• 账号切换

开发者可以通过 logout 当前账号，再 login 新账号实现此功能。

实现单聊

通过以下简单步骤可实现单聊功能，单聊是 IM 的基础功能，能够实现一对一的即时通信能力。

1. 创建单聊会话

this._imClient.createSingleConversation(toUid)

2. 发送单聊消息

//创建消息
let sendMsg = this._imClient?.createTextMessage('消息内容')
//发送消息
this.imClient.sendMessage(sendMsg, conversationId, {
  onProgress: (message: BIMMessage, progress: number) => {
    //发送进度（0～100），仅多媒体消息
  },
  onSaved: (message: BIMMessage) => {
    //消息保存到本地
  },
  onSuccess: (message: BIMMessage) => {
    //消息发送成功
  },
  onError: (message: BIMMessage, code: BIMErrorCode) => {
    BIMUILog.debug(this._tag, `sendMessage() onError:${message.getUuid()} content:${msg.innerMessage.content} status:${message.getMsgStatus()}`)
    //发送错误
  }
})

3. 设置消息监听

this._imClient?.addMessageListener(msgListener)

private  msgListener: BIMMessageListener = {
  // 收到新消息
  onReceiveMessage: (message: BIMMessage): void => {
    
  },
  // 发送消息入库完成
  onSendMessage: (message: BIMMessage): void => {
    
  },
  // 消息被删除
  onDeleteMessage: (message: BIMMessage): void => {
    
  },
  // 收到的消息被撤回
  onRecallMessage: (message: BIMMessage): void => {
    
  },
  // 收到的消息被修改。（内容+扩展）
  onUpdateMessage: (message: BIMMessage): void => {
    
  }
}

配置日志

IMSDK 提供了日志记录和性能分析功能，以帮助用户分析线上问题，默认开启，如不需要此功能可以在 initSDK 中配置 BIMSDKConfig 来关闭，实例代码如下。

let  config = new  BIMSDKConfig()
config.enableAPM = true; // 默认开启，建议开启辅助问题排查
config.enableAppLog = true; // 默认开启，建议开启辅助问题排查
this._imClient = new  BIMClient(context, appID, config)

相关文档

• IM Cloud API

• IM Cloud 回调

• IM Cloud 错误码

• IM Cloud 类型详情