@deeprespond/im-uniapp
v1.2.0
Published
DeepRespond IM UniApp 平台 SDK
Readme
UniApp IM SDK
共享 Web IM 核心,提供 @deeprespond/im-uniapp/app、/h5、/miniprogram 三个入口。App 使用原生 SQLite、安全会话、路径媒体、推送和系统来电;消息、离线队列、同步、联系人、群、聊天室及通话控制继续复用同版本核心。@deeprespond/[email protected] 已发布到 npm;正式生产发布前仍需完成下文列出的原生验收。
平台与实现范围
| 目标 | 实现 | 验证边界 |
| --- | --- | --- |
| 传统 UniApp Android / iOS | 完整 IM 平台适配、原生 LiveKit 通话和独立频道;视频使用 nvue 组件 | 原生源码与配置检查通过;Android 验证工程、HBuilderX/UTS 双端构建与真机验收待执行 |
| uni-app x Android / iOS Vapor | 同一 JavaScript 核心、UTS 插件、native-view 视频组件及完整示例 | 源码接入已提供;尚未通过 HBuilderX 与真机验证。VDOM 原生 UTS 逻辑层未支持 |
| H5 | Web SDK 的浏览器存储、消息、文件和媒体 | Web 自动化测试通过 |
| 微信 / 支付宝 / 抖音小程序 | Uni 网络/媒体 API、宿主存储和文件 API、共享快照与路径媒体 | 音视频不支持(calls/channels 的 LiveKit 媒体适配未实现);系统来电也不支持。其余 IM 适配的宿主替身测试通过,支付宝、抖音开发者工具与设备验证待执行 |
| 鸿蒙 App | 无对应原生插件 | 未实现;不因 uni-app x 名称而宣称支持鸿蒙 |
Android 最低 API 24,iOS 15。传统 App 建议 HBuilderX 5.21+;x 使用 Vapor,Android 从 5.21、iOS 从 5.11 支持(DCloud 说明)。x 编译到小程序的具体宿主支持以 HBuilderX 为准;抖音示例走传统 UniApp。
发布与安装
UniApp SDK 由 JavaScript npm 包和 App 原生 uni_modules 插件组成。@deeprespond/[email protected]、@deeprespond/[email protected]、@deeprespond/[email protected] 和 @deeprespond/[email protected] 已发布到公开 npm;deeprespond-im、deeprespond-rtc、视频组件及可选推送模块仍需从 DCloud 插件市场导入,或从对应版本压缩包解压到项目的 uni_modules/。只安装 npm 包不会把 UTS 原生插件安装到 HBuilderX 项目中。
发布后,H5 和小程序项目安装 JavaScript 包:
npm install @deeprespond/[email protected] @deeprespond/[email protected]App 项目还要安装 deeprespond-im、deeprespond-rtc;传统 UniApp 的视频页面再安装 dr-rtc-video,uni-app x Vapor 页面安装 dr-rtc-video-x。需要推送时按厂商安装相应的 deeprespond-im-push-* 模块。若使用 npm 压缩包离线安装,可把所需目录复制到项目:
mkdir -p uni_modules
cp -R node_modules/@deeprespond/im-uniapp/uni_modules/deeprespond-im \
node_modules/@deeprespond/im-uniapp/uni_modules/deeprespond-rtc \
uni_modules/App 必须使用 HBuilderX 项目、自定义基座或正式包,标准基座不包含这些原生插件。小程序的音视频通话和 RTC 频道当前不支持。
维护者发布时应先发布同版本的 @deeprespond/im-web,再发布 @deeprespond/im-uniapp,随后上传同版本 UTS 插件,并在发布说明中写明 Android/iOS 真机验收范围。发布前可运行 pnpm check:package 检查 npm 元数据、发布文件和插件版本是否一致。
构建与示例
cd sdk/web
pnpm install --frozen-lockfile
pnpm build
cd ../uniapp
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
node tools/prepare-example.mjs
node tools/check-app-bundle.mjs
node tools/check-native.mjsH5 示例
demo/ 是一个独立的原生 TypeScript H5 示例,直接使用 @deeprespond/im-uniapp/h5,覆盖初始化、Ticket/密码登录、注册、会话列表、文本消息、文件消息和 RTC 频道控制。示例中的注释和 README 均提供中英文说明,适合先在浏览器验证 SDK,再迁移到 UniApp Vue 页面。
cd sdk/uniapp/demo
cp .env.example .env.local
# 编辑 .env.local,或在页面中填写 appKey、apiUrl 和登录凭证
pnpm install
pnpm dev生产构建和类型检查:
pnpm typecheck
pnpm builddemo/README.md 说明了环境变量、H5 运行边界和最小接入代码。示例不会内置真实服务地址、密码或 Ticket。
example/ 是传统 Vue 3 App,含完整 IM 页面和前台 RTC nvue 频道页面;example-x/ 是 Android/iOS Vapor 示例,manifest.json 已启用 uni-app-x.vapor。先编辑各示例的 client.js 服务地址和公开 appKey,再在示例目录安装依赖,用 HBuilderX 打开,填写 DCloud AppID、应用包名和签名。原生插件需要自定义基座或正式打包,标准基座不包含这些插件。
App 必需复制 uni_modules/deeprespond-im 和 deeprespond-rtc;传统 nvue 视频另加 dr-rtc-video,x 普通页面视频另加 dr-rtc-video-x。可选推送模块按实际通道复制。准备脚本只复制必需模块和视频组件。
App 接入
以下代码只放在 Android/iOS App 编译分支。H5 与小程序使用各自入口。
import { createDRUniAppClient } from '@deeprespond/im-uniapp/app';
import { imCommand, imListen, imUnlisten } from '@/uni_modules/deeprespond-im';
import { rtcCommand, rtcListen, rtcUnlisten } from '@/uni_modules/deeprespond-rtc';
const im = await createDRUniAppClient({
appKey: 'org#app', apiUrl: 'https://im.example.com', uni,
native: { imCommand, imListen, imUnlisten },
rtc: { rtcCommand, rtcListen, rtcUnlisten },
// 填服务端已配置的推送凭证名称,不是通道的服务端 Secret。
push: { credentials: { apns: 'ios-prod', fcm: 'android-prod' } },
systemCalls: { useCallKit: false, useTelecom: true, appName: '我的应用' },
});
await im.auth.loginWithTicket({ ticket: userLoginTicket });
await im.messages.send({ to_user: 'bob' }, { type: 'text', body: { text: '你好' } });
const file = await im.importFile(pickerPath, { name: 'photo.jpg' });
await im.messages.send({ to_user: 'bob' }, { type: 'image', file });
const call = await im.calls.start({ to_user: 'bob', media: 'audio' });
// 页面切换保留单例;退出登录用 auth.logout,结束客户端用 destroy。
await call.hangup();
await im.destroy();createDRUniAppClient 是异步工厂:先校验原生协议并载入安全会话,再返回客户端。一个原生插件实例只创建一个客户端。恢复登录由共享核心完成;安全存储确认落盘后登录才成功。rtc 参数可省略,此时 calls.supported 为 false。
本地文件使用 { path, name?, temp? },不依赖 Blob。importFile 将选择器路径或 Android content:// 内容复制到 SDK 临时目录;再交给 files.prepare、files.upload 或消息发送。附件在进入队列前持久复制,上传/下载走原生流式 I/O,支持进度和取消;图片处理、视频元数据扫描/缩略图、AAC 录音、按账号隔离的下载缓存均已接入。录音中断通过 ended 返回已有片段;账号退出会取消录音和传输。
会话使用 Android Keystore / iOS Keychain 持有 AES-GCM 密钥,安全数据与数据库按 appKey、API origin 和用户名隔离。卸载后的恢复不复用旧会话。SQLite 提供真实事务、排序索引及严格队列写入;此实现采用共享核心的 JSON 记录契约,不承诺与 Flutter / Android 原生 SDK 的数据库文件直接互换。
推送
登录后按配置自动登记全部通道令牌,刷新时重新登记;暂时未取到的令牌保留上次值,确认不可用的通道移除。前后台接收与冷启动点击经原生持久队列回放,要求服务端推送载荷携带精确的字符串 session_id。本次同步补了服务端该字段和隐藏预览下的来电截止时间;旧服务端缺字段的载荷不会触发 SDK 回调或系统来电。
await im.devicePush.requestPermission(); // 在用户主动授权时调用
await im.devicePush.register();
const off = im.devicePush.onClick(payload => { /* 按 conversation_id / collapse_id 导航 */ });- iOS APNs:启用应用 Push Notifications、正确的
aps-environment签名、通知权限和服务端 APNs 凭证。自定义基座须勾选 Push 模块才能接收 DCloud 推送生命周期回调;由 SDK 控制注册时将宿主pushRegisterMode配为manual。原生层接收 APNs Token 并转发已有通知代理;info.plist含后台音频与远程通知声明。 - Android FCM:复制
deeprespond-im-fcm。应用须配置 Firebase 默认应用资源;只有安装 SDK 不会自动生成配置。可按 Firebasegoogle-services.json为应用生成google_app_id、google_api_key、gcm_defaultSenderId、project_id等 string 资源,放入宿主 Android 资源,或由宿主 Gradle 的 Google Services 插件生成。不要将服务账号密钥放入 App。FCM 数据消息由唯一的IMFirebaseMessagingService接收。 - Huawei / Honor / Meizu:分别复制
deeprespond-im-push-huawei/honor/meizu,依赖通过各模块 Maven 配置获取;Huawei 需宿主 AGConnect 配置,Honor 需宿主com.hihonor.push.app_id元数据。 - Xiaomi / OPPO / vivo:分别复制对应模块并由宿主提供厂商 SDK/AAR、权限及厂商配置;模块用反射检测 SDK,未安装时返回 unavailable。厂商 AAR 未随仓库分发。
- iOS 支持系统角标。Android 返回 launcher-managed,角标由厂商通知渠道/桌面管理;不要据此宣称各厂商角标均已真机通过。
厂商令牌适配器的接法(只放在 Android 编译分支):
import { createNativePushProvider } from '@deeprespond/im-uniapp/app';
import * as huawei from '@/uni_modules/deeprespond-im-push-huawei';
// createDRUniAppClient 的 push 配置:
const push = {
credentials: { huawei: 'hms-prod' },
providers: [createNativePushProvider('huawei', huawei)],
};Xiaomi / Meizu 传 { appId, appKey },OPPO 传 { appKey, appSecret },vivo 使用宿主厂商配置。这里是厂商给客户端的公开应用配置,IM 租户密钥和推送服务端私钥仍留在服务端。厂商通知点击进入 impush 深链后提取业务载荷;通道能否在进程回收后唤醒后台通话取决于厂商能力、配置和系统策略,必须逐通道验收。
系统来电与后台通话
Android 集成来电通知、接听/拒绝/挂断操作、Core-Telecom 和电话/麦克风/摄像头前台服务。Android 14+ 可用 systemCalls.canUseFullScreenIntent() 检查全屏来电授权,再由应用按场景调用 openFullScreenIntentSettings()。
iOS CallKit/PushKit 默认关闭;允许使用的应用通过 useCallKit: true 开启,配置 push.voipCredential、VoIP 推送签名、UIBackgroundModes 的 voip、audio 与 remote-notification,并使用相应服务端凭据。每次 VoIP 到达都会向系统报告来电,过期或账号不匹配的来电立即结束。CallKit/PushKit 的可用地区与上架配置由接入应用确认。
来电动作绑定原登录会话;拒绝/挂断可由原生 HTTP 执行,接听回放给共享通话控制。calls 单聊/群通话的后台控制已有源码:原生心跳延长媒体控制租约,令牌续期与前台 SDK 共用原生串行路径;账号变更、控制失败或租约到期关闭媒体,真机验收仍待完成。channels 独立 RTC 频道现在保留原生 LiveKit 房间并支持后台音频;Android 进入后台时启动 RTC 前台服务,iOS 使用音频后台模式。频道的成员心跳和媒体凭据续期仍由共享核心执行,视频采集受系统后台限制;后台音频、权限、弱网和设备回收仍需真机验收。原生轨道是 NativeRTCTrack,不是 MediaStreamTrack;视频组件只接收 SDK 轨道提供的 roomId/trackId。
H5 与小程序
H5 使用 createDRUniAppH5Client(@deeprespond/im-uniapp/h5)。小程序示例:
import { createDRUniAppMiniProgramClient } from '@deeprespond/im-uniapp/miniprogram';
// 各宿主分别传 wx / my / tt;不要在其他目标访问这些全局对象。
const im = createDRUniAppMiniProgramClient({
appKey: 'org#app', apiUrl: 'https://im.example.com', uni,
native: wx, mp: 'weixin',
});微信基础库至少 2.21.3。支付宝适配对象形式的存储 API,不宣称提供微信的 encrypt 存储。抖音需支持二进制 readFile({ position, length });遇到忽略读取范围的旧基础库明确拒绝,不回退到整文件读取。配置请求、Socket、上传和下载合法域名。快照限制、文件大小、媒体类型及前后台规则沿用小程序适配说明。
共享适配层归 sdk/web/src/uniapp/ 和 sdk/web/src/platform/miniprogram/;本包依赖同版本 Web 核心,不依赖微信小程序预打包包。App 和小程序构建检查确保不引入浏览器 LiveKit。
验证与交付
示例工程: H5 Demo、微信小程序 Demo、Android/iOS App Demo。三套 Demo 的自动化测试步骤、截图和环境边界见 sdk-uniapp Demo 测试索引。
Demo projects: H5, WeChat Mini Program, and Android/iOS App. Their test steps, screenshots, and environment boundaries are recorded in the sdk-uniapp demo test index.
实现与验证记录见 5.平台能力交付。Android 独立验证工程编译所有 IM/RTC/推送 Kotlin 源码,不代替 UTS 编译:
gradle -p sdk/uniapp/verify/android assembleDebugiOS 当前只有源码与语法检查,尚未通过 Swift 类型检查、Xcode 链接。正式交付仍须完成 HBuilderX 双端自定义基座构建、真实签名/推送凭据、各宿主开发者工具及 Android/iOS 真机。尤其需要验收后台回收/来电接听、CallKit 音频路由、弱网重连、大文件、账号切换与跨端互通。现有独立频道文档见 RTC.md。
