集成 HarmonyOS SDK - IM 即时通讯

更新时间： 2026/08/14 10:26:43

网易云信即时通讯 SDK（NetEase Instant Messaging SDK，简称 NIM SDK）为 HarmonyOS 项目提供完善的即时通信功能开发能力。NIM HarmonyOS SDK 屏蔽其内部复杂细节，对外提供较为简洁的 API，方便您快速集成即时通信功能。

本文主要介绍底层 HarmonyOS SDK 的集成，若您需要集成对应的 UI 组件，请参考集成 HarmonyOS UIKit。

功能模块

IM HarmonyOS SDK 提供的功能包括登录、会话、消息、群组、用户、好友、存储服务、推送、自定义通知、设置、信令、聊天室、圈组等功能。

对应上述功能提供业务组件 har 包，包括 conversation、conversationgroup、localconversation、message、team、user、friend、signalling、chatroom、qchat。模块架构如下图所示：

开发环境

根据华为官网数据，目前基本为 API 17 及以上设备。因此为了提供更多高版本 API 特性，NIM SDK 自 V10.10.1 版本起，将 API 支持的最低版本提升到 API 17。

DevEco Studio NEXT Developer（6.1.1）及以上。
HarmonyOS SDK API 17 及以上。

集成 SDK

通过官网下载 .har 形式的 NIM SDK 产物。
将 SDK 文件拷贝到 HarmonyOS 工程，例如放至 entry 模块下的 libs 目录。

修改模块目录的 oh-package.json5 文件，在 dependencies 节点增加依赖声明。

本地依赖：

localconversation 与 conversation、conversationgroup 为互斥关系，不可以同时使用。

JSON{
    "name": "entry",
    "version": "1.0.0",
    "description": "Please describe the basic information.",
    "main": "",
    "author": "",
    "license": "",

    ...

    "dependencies": {
        // 业务模版 har 包，可以按需添加
        "@nimsdk/conversation": "file:../../libs/conversation.har",
        // 业务模版 localconversation 与 conversation 和 conversationgroup 为互斥关系，不可以同时使用
        "@nimsdk/localconversation": "file:../../libs/localconversation.har",
        "@nimsdk/message": "file:../../libs/message.har",
        "@nimsdk/team": "file:../../libs/team.har",
        "@nimsdk/user": "file:../../libs/user.har",
        "@nimsdk/friend": "file:../../libs/friend.har",
        "@nimsdk/signalling": "file:../../libs/signalling.har",
        "@nimsdk/chatroom": "file:../../libs/chatroom.har",
        "@nimsdk/qchat": "file:../../libs/qchat.har",
        // HarmonyOS IMSDK 基础业务模块，必须添加
        "@nimsdk/nim": "file:../../libs/nim.har",
        "@nimsdk/base": "file:../../libs/base.har",
        // HarmonyOS IMSDK 检索模块，如需要使用本地检索功能，必须添加
        "@nimsdk/search": "file:../../libs/search.har"
    }
  ...

}

云端依赖（以10.10.13 版本为例）：

localconversation 与 conversation、conversationgroup 为互斥关系，不可以同时使用。

JSON{
    "name": "entry",
    "version": "1.0.0",
    "description": "Please describe the basic information.",
    "main": "",
    "author": "",
    "license": "",

    ...

    "dependencies": {
        // 业务模版 har 包，可以按需添加
        "@nimsdk/conversation": "10.10.13",
        // 业务模版 localconversation 与 conversation 和 conversationgroup 为互斥关系，不可以同时使用
        "@nimsdk/localconversation": "10.10.13",
        "@nimsdk/message": "10.10.13",
        "@nimsdk/team": "10.10.13",
        "@nimsdk/user": "10.10.13",
        "@nimsdk/friend": "10.10.13",
        "@nimsdk/signalling": "10.10.13",
        "@nimsdk/chatroom": "10.10.13",
        "@nimsdk/qchat": "10.10.13",
        // HarmonyOS IMSDK 基础业务模块，必须添加
        "@nimsdk/nim": "10.10.13",
        "@nimsdk/base": "10.10.13"
    }
  ...
}

示例代码中的插件关系如下（实线箭头表示强引用关系，虚线箭头表示弱引用关系）：

单击 File > Sync and Refresh Project 按钮，直到同步完成。

在工程 build-profile.json5 中设置支持字节码 HAR 包。

V10.9.10 及以上版本都必须引入。

JSON{
  "app": {
    "products": [
      {
        "buildOption": {
          "strictMode": {
            "useNormalizedOHMUrl": true
          }
        }
      }
    ]
  }
}

调用 API

集成 NIM SDK 后，所有 SDK 能力均通过 NIM SDK 实例提供的 service 进行调用，例如：

通过 loginService 进行登录：

initializeOptions.appkey 为必填项；如配置数据库服务，databaseServiceConfig.appKey 必须与其保持一致。公有云默认使用 TCP，显式配置 TCP LBS 时使用 linkLbsUrls，lbsUrls 用于 WebSocket LBS。

TypeScriptconst nim: NIMInterface = NIMSdk.newInstance(context, initializeOptions, serviceOptions)

nim.loginService.on('onLoginStatus', loginStatus => {
console.log('收到 V2NIMLoginService 模块的 onLoginStatus 事件', loginStatus);
})
await nim.loginService.login("YOUR_ACCOUNT", "YOUR_TOKEN")

通过 messageService 进行消息发送：

TypeScript  const message = nim.messageCreator.createTextMessage("hello")
  nim.messageService?.sendMessage(message, 'YOUR_ACCOUNT|1|RECEIVER_ACCOUNT')

数据库备份恢复

IM 应用高度依赖本地数据库能力。会话列表、历史消息、未读数、同步游标、群组与用户资料等核心数据都需要在本地持久化，以保证弱网、离线、重启后的使用体验。

在少数异常场景下，本地数据库可能出现损坏或无法正常打开，例如应用进程在数据库写入过程中被强制终止、系统异常重启、设备存储空间不足、文件系统异常、数据库迁移过程中被中断等。数据库异常会影响登录后的数据加载、历史消息展示和本地同步状态恢复。

为提升本地数据可靠性，NIM SDK 提供数据库备份恢复能力。开启后，SDK 会在合适时机自动生成本地数据库备份，并在数据库打开失败或健康检查异常时，优先尝试从有效备份恢复，降低数据库损坏对 IM 核心功能的影响。

开启 backupEnabled 后，SDK 会自动完成备份生成、备份校验、旧备份清理和异常恢复。业务侧只需在初始化参数中开启配置，无需手动调用备份或恢复接口。
只有当 SDK 将打开阶段错误判定为可恢复的数据库损坏，并且存在经过校验的有效备份组时，SDK 才会尝试恢复。
配置错误、密钥错误、空间不足、锁冲突等非数据库损坏错误不会统一进入恢复流程。
开启该能力后，SDK 会额外占用一定本地存储空间用于保存备份文件，并在备份、校验、清理和恢复过程中产生少量 I/O 开销。建议业务根据自身数据可靠性要求、设备存储情况和性能策略决定是否开启。

在 SDK 初始化时，通过 databaseServiceConfig 开启数据库备份能力：

TypeScript  const options = {
    databaseServiceConfig: {
      appKey: 'YOUR_APPKEY',
      backupEnabled: true,
      backupRetentionCount: 2,
      backupIntervalHours: 12,
      healthCheckOnOpen: true,
      autoRecoverOnOpenFailure: true
    }
  }

参数说明：

参数	类型	默认值	说明
`appKey`	string	无	数据库服务使用的 AppKey，必须与 `initializeOptions.appkey` 一致。
`backupEnabled`	boolean	false	是否开启数据库备份恢复能力。
`backupRetentionCount`	number	2	保留最近有效备份组数量。
`backupIntervalHours`	number	12	最小备份间隔，单位小时。
`healthCheckOnOpen`	boolean	true	打开数据库时是否执行健康检查。
`autoRecoverOnOpenFailure`	boolean	true	数据库打开失败时，满足可恢复条件且存在有效备份时是否自动尝试恢复。

API 参考

您可以参考 API 概览，查看并了解 NIM SDK API。

下一步

完成 SDK 集成后，您可以尝试初始化。

此文档是否对你有帮助？

有帮助

去反馈

功能模块
开发环境
集成 SDK
调用 API
数据库备份恢复
API 参考
下一步