晞晗IM · XHIM

主题

晞晗IM iOS Demo ​

这是一个面向普通体验者和 iOS 开发者的 UIKit 聊天应用，不是 SDK 验收台。 打开后用手机号注册或登录，就能像普通 IM 一样使用“消息、通讯录、我的”三个 页面。

直接运行 ​

  1. 安装 Xcode 16 或更高版本。
  2. 如未安装 XcodeGen，执行 brew install xcodegen。
  3. 在终端执行：
bash
cd platforms/ios/Examples/XHIMUIKitDemo
./Scripts/sync_resources.sh
xcodegen generate
open XHIMUIKitDemo.xcodeproj
  1. 在 Xcode 中选择 XHIMUIKitDemo Scheme 和模拟器后点击运行。
  2. 真机运行时，只需在 Signing & Capabilities 中选择你自己的 Apple Team。

SDK 是预编译二进制包，体验者不需要安装 C++、Docker 或服务端工具，也不需要 晞晗软件的证书。

两台设备互相聊天 ​

默认服务器是：

text
https://im.xihansoftware.com/xhim-api
  • 第一台设备输入一个手机号，切换到“注册”，设置密码并完成登录；
  • 第二台设备用另一个手机号完成注册登录；
  • 在通讯录点击“添加朋友”，默认输入对方注册时使用的完整手机号。Demo 会先 精确查询并展示对方的头像、昵称和晞晗号，确认无误后才发送申请，再由另一端 同意；
  • 如果不知道手机号，可切换到“晞晗号”，让对方在“我的”页面点击复制完整 晞晗号后查询；
  • 以后直接使用手机号和密码登录，不再依赖代码里预置的 A/B 账号。

手机号查找只支持单个完整号码的精确匹配，例如 13800138000 或 +8613800138000；不支持手机号片段、昵称、模糊或批量搜索。查找成功后 SDK 返回内部 userID（Demo 中显示为晞晗号），再由 Demo 把该 ID 传给 sendFriendRequest(toUserID:)，不要把手机号直接当作 userID。

Development Server 使用演示注册目录完成手机号查找。正式私有化部署必须接入 客户自己的用户目录，并配置“允许通过手机号被发现”的隐私开关、App 隔离、 鉴权、限流和防枚举策略；iOS App 与 SDK 不直接读取手机号身份表。

登录页的“服务器设置”只供私有化部署客户修改。普通体验无需填写 User ID、 Token、App ID 或管理员密钥。手机号演示账号只在 Development Server 开启； 正式产品接入客户自己的短信验证、风控和业务账号系统。

登录页会自动检测服务端能力。只有 Server 的公开配置同时声明能力协议 v1、 Development 环境和手机号认证已开启，手机号表单才可操作。网络临时失败可点击 “重新检测服务器”；提示“当前服务器未提供手机号注册登录”时，应先升级服务端， 而不是修改手机号、写死 Token 或切回预置 A/B 账号。

前后端发布必须按以下顺序完成：

  1. 服务端升级并完成数据库迁移；
  2. 服务端验证健康检查、手机号能力字段以及“注册 → 密码登录”闭环；
  3. 再向设备安装新版 Demo；
  4. Demo 登录页显示绿色“已支持手机号登录”后再注册。

如果提示“该手机号已经注册”，应切换到“登录”，而不是继续重复注册；如果提示 “手机号或密码不正确”，请核对原注册密码，Demo 不会泄露该手机号是否存在。 Server 的标准错误响应字段是 code。出现笼统的 http_401、http_409 或 “操作未完成，错误 1”，说明设备仍在运行旧 Demo，应重新构建并覆盖安装。

Demo 已包含的功能 ​

  • 登录、退出、用户资料和服务器切换；
  • 会话列表、未读数、单聊、消息搜索和草稿；
  • 文本、表情、图片、拍照、视频、文件、录音、位置、名片和自定义消息；
  • 消息发送状态、失败重试、编辑、撤回、本地删除和安全附件下载预览；
  • 好友申请的收发方向、同意/拒绝、好友备注、删除好友和黑名单；
  • 群聊创建、入群审批、成员/管理员/禁言管理、群主转让、退群和解散；
  • 输入状态、服务端已读回执、实时消息更新和 APNs 设备登记。

聊天页左下角“+”会展开相册、拍摄、视频、文件、录音等附件入口；笑脸按钮会 展开表情面板，点击表情后会立即插入输入框。

真实服务端自动化测试 ​

普通构建不会访问网络。需要验证两个账号经远端服务互发消息时执行：

bash
xcrun simctl spawn booted launchctl setenv \
  XHIM_INTEGRATION_SERVER https://im.xihansoftware.com/xhim-api

xcodebuild \
  -project XHIMUIKitDemo.xcodeproj \
  -scheme XHIMUIKitDemo \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
  test

集成测试会通过 Development 手机号接口生成本轮独立的随机账号，并覆盖注册、 好友申请与处理、备注、黑名单、单聊、富媒体收发与校验、已读、消息修改、群组 治理和关系删除。测试不会依赖预置 A/B 账号，也不会在日志中输出手机号、密码或 登录凭证。

APNs 的客户端登记链路可以在模拟器编译和单元测试中验证；真实通知到达仍需要 宿主 App 的 Push Notifications 能力、有效的 APNs entitlement，以及部署方在 Server 配置与 Bundle ID 匹配的 APNs 凭证。SDK 和 Demo 不内置晞晗软件或客户 的推送证书。用户点击消息通知后，Demo 会读取 xhim.resource_id（兼容 conversation_id）和 xhim.recipient_user_id，仅在通知所属账号与当前登录 账号一致时进入对应会话；这样退出 A 再登录 B 时不会错误打开 A 的通知。冷启动 时带账号身份的新通知会等待对应账号连接，无账号身份的旧通知不会跨账号保留。

项目结构 ​

text
Application/       App 生命周期、登录/主界面路由
Core/              通用主题、图标与基础组件
Features/Auth/     登录
Features/Chats/    会话、聊天、表情与附件
Features/Contacts/ 通讯录、好友、群聊与黑名单
Features/Profile/  个人中心
Infrastructure/    SDK 会话和本地配置

界面图标来自仓库锁定版本的 Lucide SVG，工程中保留 ISC 许可证和可编辑源文件。

XHIM 客户端 SDK 与服务端文档

© 2026 晞晗软件 · Xihan Software