快速入门

本教程旨在帮助开发者快速了解和掌握 IMLib SDK (融云即时通讯能力库) 的基础集成流程与核心通信能力。通过本教程，您将完成 IMLib SDK 导入、初始化、设置监听、建立连接和发送消息等全流程操作。

环境要求

• DevEco Studio NEXT Release(5.0.3.900) 及以上。
• HarmonyOS SDK API 12 及以上。
• 手机系统版本号：NEXT.0.0.31。
• 真机华为 Mate 系列。真机运行需要配置证书，详情参考鸿蒙的签名指南文档。
• 模拟器。详情参考鸿蒙的模拟器运行指南文档。

准备工作

1. 访问融云控制台，注册您的开发者账号。注册成功后，控制台自动在开发环境中为您创建一个应用。

2. 在控制台的密钥管理页面，获取您的应用在开发环境的 App Key。您可在密钥管理页面查看应用的信息，如 App Key、App Secret、所属数据中心（默认为北京）。 您可以创建应用，并获取对应环境 App Key 和 App Secret。

   提示

   每个应用均拥有两个不同的 App Key，分别对应开发环境与生产环境，且两个环境之间数据相互隔离。在您的应用正式上线前，建议切换到生产环境的 App Key，以便完成上线前全流程测试和最终发布。

导入 SDK

融云支持从 OpenHarmony三方库中心仓 添加依赖和将 IMLib 相关的 SDK 文件本地库导入应用工程两种集成方式。

以下介绍如何使用从 OpenHarmony三方库中心仓 添加依赖方式将 IMLib SDK 导入工程：

1. 在鸿蒙主工程 entry 目录中的 oh-package.json5 中添加 SDK 依赖，然后点击 "Sync Now"。

   JSON

   // entry 目录中的 oh-package.json5
   {
     "name": "entry",
     "version": "1.0.0",
     "description": "Please describe the basic information.",
     "main": "",
     "author": "",
     "license": "",
     "dependencies": {
       "@rongcloud/imlib" : "x.y.z"
     }
   }
   
   提示

   各个 SDK 的最新版本号可能不相同，具体 x.y.z 值，可前往 融云官网 SDK 下载页面 或 OpenHarmony三方库中心仓 查询。

2. 安装 SDK 成功后，您可以在项目根目录的 oh_modules/.ohpm/ 中找到融云 IMLib SDK。

   

项目配置

1. 添加 SDK 依赖权限

添加如下权限：

权限名称	权限说明	使用目的
ohos.permission.GET_NETWORK_INFO	获取网络信息	网络变化之后获取网络信息，进行 IM 重连
ohos.permission.INTERNET	使用网络	连接 IM 、收发消息需要网络连接
ohos.permission.STORE_PERSISTENT_DATA	数据存储	消息数据库需要本地存储

详情参考鸿蒙应用权限配置文档。

2. 配置 useNormalizedOHMUrl

1.0.3 版本开始 SDK 支持字节码，为了支持字节码，App 需要在项目根路径配置 useNormalizedOHMUrl。

// app 根路径下的 build-profile.json5
{
  "app": {
    "products": [
      {
         "buildOption": {
           "strictMode": {
             "useNormalizedOHMUrl": true
           }
         }
      }
    ]
  }
}

详细信息请参考 FAQ。

初始化 SDK

IMLib SDK 初始化接口的调用需要引入对应的声明：

TypeScript

import { IMEngine } from '@rongcloud/imlib';

为确保您可以正常连接融云服务器和使用融云即时通讯服务（IM 服务），您须调用 init 方法初始化 IMKit SDK。初始化前，您须在融云控制台中获取 App Key，并设置好 InitOption（初始化配置）。

InitOption 中封装了 areaCode （数据中心的区域码），naviServer（导航服务地址）、statisticServer（数据统计服务地址）。

如果您使用北京数据中心，则不需设置 InitOption，IMKit SDK 默认连接北京数据中心。

TypeScript

// 初始化 SDK
let initOption = new InitOption();
IMEngine.getInstance().init(getContext(), "Your_AppKey", initOption);

如果您使用海外数据中心，则须传入海外数据中心对应的 AreaCode。

TypeScript

// 初始化 SDK
let initOption = new InitOption();
initOption.areaCode = AreaCode.SG;
IMEngine.getInstance().init(getContext(), "Your_AppKey", initOption);

初始化详细说明参见初始化。

监听消息

通过设置消息接收监听器，用户可接收所有类型的实时消息和离线消息。

提示

为确保接收所有离线消息，请在初始化 SDK 后，连接 IM 融云服务器之前设置监听器。

TypeScript

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

连接融云 IM 服务器

用户 Token 是与用户 ID 对应的身份验证令牌，是应用程序的用户在融云的唯一身份标识。应用客户端在使用融云即时通讯功能前必须与融云建立 IM 连接，连接时必须传入 Token。

在实际业务运行过程中，应用客户端需要通过应用的服务端调用 IM Server API 申请取得 Token。详见 Server API 文档 注册用户。

在本教程中，为了快速体验和测试 SDK，您可以前往控制台的密钥管理页面，在 管理测试用户 区域输入用户 ID 1，点击 获取 Token 生成该用户的 Token。

1. 为模拟用户通过融云 IM 服务器收发消息，您需要首先注册一个用户。在实际业务中，应用客户端通过应用服务端调用融云 IM Server API 获取 token。详见 Server API 文档注册用户。在本教程中，为了快速体验融云服务，您可以前往控制台的密钥管理页面，在 管理测试用户 区域输入用户 ID 1，点击 获取 Token 生成该用户的 Token。返回示例如下：

HTTP

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200,"userId":"1","token":"gxld6GHx3t1eDxof1qtxxYrQcjkbhl1V@sgyu.cn.example.com;sgyu.cn.example.com"}

2. 设置连接监听器来实时获取连接状态。您可以将连接状态通过 UI 反馈给用户（例如提示 “网络连接中断” 或 “已重新连接”），提高用户体验。建议在应用生命周期内，初始化 SDK 之后，连接 IM 之前设置 IM 连接状态监听器。详见设置连接状态监听。

   TypeScript

   IMEngine.getInstance().setConnectionStatusListener((status: ConnectionStatus) => {
   });

3. 调用 connect 方法，将 userId 为 1 的用户连接融云 IM 服务。 注：IMLib SDK 有重连机制，因此一个应用生命周期内调用一次 connect 即可，详见连接。

   TypeScript

   let token = "IMToken";
   let timeout = 30;
   
   IMEngine.getInstance().connect(token, timeout)
     .then(result => {
     });
   

发送消息

最后，您可以模拟向 userId 为 2 的用户发送一条文本消息。除了文本消息，您还可发送图片、文件、语音、文件等不同类型的消息，详见[消息类型]。

示例代码

TypeScript

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

// 创建文本消息
let textMsg = new TextMessage();
textMsg.content = "from 鸿蒙 ";
textMsg.extra = "TestExtra";

let option: ISendMsgOption = {};

// 创建消息体
let msg = new Message(conId, textMsg);


// 发送消息
IMEngine.getInstance().sendMessage(msg,option,(msg: Message) => {
    // 消息入库回调
}).then(result => {
    // 消息发送结果
})