跳到主要内容

快速入门

本教程是为了让新手快速了解融云即时通讯能力库（IMLib）。在本教程中，您可以体验集成 SDK 的基本流程和 IMLib 的基础通信能力。

前置条件​

  • 注册开发者账号。注册成功后，控制台会默认自动创建您的首个应用，默认生成开发环境下的 App Key，使用国内数据中心。

  • 获取开发环境的应用 App Key。如不使用默认应用，请参考 如何创建应用，并获取对应环境 App Key 和 App Secret。

    提示

    每个应用具有两个不同的 App Key，分别对应开发环境与生产环境，两个环境之间数据隔离。在您的应用正式上线前，可切换到使用生产环境的 App Key，以便上线前进行测试和最终发布。

  • 创建鸿蒙应用

编译环境​

  • DevEco Studio NEXT Release(5.0.3.900) 及以上。
  • HarmonyOS SDK API 12 及以上。
  • 手机系统版本号：NEXT.0.0.31

设备要求​

  • 真机华为 Mate 系列。真机运行需要配置证书，详情参考鸿蒙的签名指南文档。
  • 模拟器。详情参考鸿蒙的模拟器运行指南文档。

开始集成​

自动导入 SDK​

1.2.0 版本开始支持从 OpenHarmony三方库中心仓 获取 SDK

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

    // 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"
      }
    }
    partner SDK
    提示

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

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

    自动导入 SDK 成功

  3. 查看更多其他融云 SDK。打开OpenHarmony三方库中心仓，搜索关键字 rongcloud。

添加 SDK 依赖权限​

添加如下权限：

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

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

配置 useNormalizedOHMUrl​

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

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

详细信息请参考 FAQ。

初始化 SDK​

融云即时通讯客户端 SDK 核心类为 IMEngine 在 UIAbility 的 onCreate() 方法中，调用初始化方法，传入生产或开发环境的 App Key。

// 在 UIAbility 中获取 context
let context = this.context

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

初始化配置 InitOption 中封装了区域码 AreaCode，导航服务地址 naviServer ，统计服务地址 statisticServer ，文件下载路径 mediaSavePath

SDK 默认连接北京数据中心，如果 App Key 不属于中国（北京）数据中心，则必须传入有效的初始化配置。初始化详细说明参见初始化。

获取用户 Token​

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

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

在本教程中，为了快速体验和测试 SDK，我们将使用控制台「北极星」开发者工具箱，从 API 调试页面调用 获取 Token 接口，获取到 userId 为 1 的用户的 Token。提交后，可在返回正文中取得 Token 字符串。

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"}

建立 IM 连接​

  1. 监听 IM 连接状态的变化，以便 UI 上给用户以提示，提高体验。

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

  2. 使用以上步骤中获取的 Token, 模拟 userId 为 1 的用户连接到融云服务器。

    let token = "IMToken";
    let timeout = 5;

    hilog.info(0x0000, 'IM-App', 'connect token:%{public}s', token);
    IMEngine.getInstance().connect(token, timeout)
      .then(result => {
        hilog.info(0x0000, 'IM-App', 'connect result :%{public}s', JSON.stringify(result));
      });

    SDK 已实现自动重连机制，请参见连接。

监听消息​

设置消息接收监听器，用于接收所有类型的实时或者离线消息。

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

发送消息​

向 userId 为 2 的用户发送一条消息。

// 创建会话标识
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);


// 发送消息
hilog.info(0x0000, 'IM-App', 'SendTextMessage start');
IMEngine.getInstance().sendMessage(msg,option,(msg: Message) => {
    // 消息入库回调
  hilog.info(0x0000, 'IM-App', 'SendTextMessage onSave msg:%{public}s', JSON.stringify(msg));
}).then(result => {
    // 消息发送结果
  hilog.info(0x0000, 'IM-App', 'SendTextMessage onResult :%{public}s', JSON.stringify(result));
})
最后于 更新