HarmonyOS IMLib 快速开始
本页用 5 个步骤完成 HarmonyOS 端 IMLib 接入：控制台取 AppKey / Token、导入 SDK、初始化、建立连接、收发消息与会话。示例方法名与参数来自冻结的 sdk-bindings.json。
本平台当前为 reserved：契约已备、未实现：本文件只有 ArkTS 签名映射，无源码、无构建、无运行证据。 下列代码为契约样例（已标注预留），不可直接运行。
- 控制台获取 AppKey 与 Token
在控制台创建应用并获取 AppKey；用户 Token 由业务服务先注册用户（
user.register）、再调用user.token.issue签发后下发到客户端（两步都需要服务端签名）。客户端只持有 Token，不得内置 AppSecret；Token 泄露时可调用服务端接口吊销。
- 导入 SDK
按「导入 SDK」安装依赖；包名
@ni-paas-im/harmony（预留，当前版本未发布）；IMKit 包名@ni-paas-im/harmony-imkit（预留）。 - 初始化客户端
使用 AppKey（与服务端地址）初始化；初始化幂等：同 appkey 重复调用返回同一实例，不建立连接。
- 建立连接并订阅事件
使用 Token 调用 connect，成功后触发 CONNECTED；离线消息在 hello 后自动补发。
- 收发消息与会话
注册对端用户后发送第一条文本消息、监听 MESSAGES 事件并拉取会话列表。
1. 控制台获取 AppKey 与 Token
| 凭据 | 获取方式 | 使用位置 |
|---|---|---|
| AppKey | 控制台 → 应用 → 基本信息 | 初始化客户端（options.appkey） |
| 用户 Token | 业务服务注册用户（user.register）后调用 user.token.issue 签发（需签名） | connect(token) |
| AppSecret | 控制台 → 应用 → 密钥（仅服务端保存） | 服务端签发 Token / 调用 Open API |
AppSecret 只能保存在业务服务端；客户端产物中不得出现 AppSecret。示例中的 TOKEN 表示服务端签发的用户 Token。
本页及后续示例统一使用 https://im.example.com（服务端缺省端口）。
示例使用占位地址 https://im.example.com；本地联调请替换为你实际启动的服务端地址与端口（客户端与服务端必须指向同一地址）。
2. 导入 SDK
// ohpm（预留包名，当前版本未发布）
ohpm install @ni-paas-im/harmony3. 初始化
// HarmonyOS 绑定为契约预留，以下为声明样例
const client: IMClient = IMClient.getInstance({
appkey: 'YOUR_APP_KEY',
serverUrl: 'https://im.example.com',
});4. 建立连接
// HarmonyOS 绑定为契约预留，以下为声明样例
const res = await client.connect(TOKEN);
if (res.code !== 0) { console.error(res.msg); }5. 收发消息与会话
收发验证需要两个已注册用户：先注册对端（例如 user2）并签发它的 Token，再用对端账号建连接收。示例中的 user2 是“已存在的另一个用户”，不是任意字符串。
// HarmonyOS 绑定为契约预留，以下为声明样例
const sent = await client.sendTextMessage(ConversationType.PRIVATE, 'user2', '你好，NI PaaS');
const conversations = await client.getConversationList();单聊发送给不存在的用户时，服务端返回 1004（用户不存在），当前连接可能因此被断开，随后发送调用返回 3001（连接已中断）。
这不是网络故障：注册对端用户（user.register）并重连后即可正常发送。排查时先确认两个 userId 都已注册且属于同一个 appkey。
如果脚本报 Unexpected token '<' 或看到 HTML，通常是服务端地址或端口不对（示例使用占位地址；本地联调要替换为实际端口）。
先用浏览器或 curl 访问服务端根路径确认可达，再检查 serverUrl 是否与启动参数一致。
同一进程内对同一个 appkey 初始化只会得到一个客户端实例（初始化幂等）：把两个账号塞进同一个实例会互相覆盖登录态，典型报错是 “cannot send to self”。
实测：同一进程内建两个客户端实例（不同 appkey 或先 destroy 再 create）可以互发；同 origin 的两个浏览器标签共享 deviceId，第二个客户端可能收不到投递。
因此本机验证“收发”请开两个进程，或开两个浏览器 profile（各自独立 localStorage/deviceId），每个进程/Profile 只登录一个用户。
下一步
- 初始化：全部初始化选项与平台差异
- 功能列表：103 个操作
- API 参考
- 状态码：处理 1002 / 3001 / 3002 等常见错误
- HarmonyOS IMKit：需要现成 UI 时使用