XuqmGroup-Web/docs-site/docs/rn/push.md

推送接入

@xuqm/rn-push 负责把宿主登录用户同步给原生推送模块，并提供离线推送开关与免打扰 设置。厂商识别、Token 获取和绑定由原生实现完成，RN 页面不接收或上传厂商 Token。

安装

pnpm add @xuqm/rn-common @xuqm/rn-push

Android 原生推送依赖按租户平台为当前应用生成的配置接入。宿主只启用实际使用的厂商 渠道，不要把其他项目的厂商 App ID 或密钥复制过来。

登录后自动绑定

宿主仍然只调用公共登录入口：

import { XuqmSDK } from '@xuqm/rn-common'

await XuqmSDK.login({
  userId: 'user-001',
  accessToken: 'host-access-token',
})

已安装 Push 模块时，会话变化自动同步到原生层。不要调用不存在的 Token 注册方法，也不要建立第二套 Push 登录 API。

登出：

await XuqmSDK.logout()

离线推送开关

import { PushSDK } from '@xuqm/rn-push'

await PushSDK.setOfflinePushEnabled(false)
await PushSDK.setOfflinePushEnabled(true)

该开关同步到当前登录用户。未登录时不要在业务页面展示为已经保存成功。

免打扰

await PushSDK.setQuietHours('22:00', '08:00')

时间使用 24 小时制的 HH:mm。清除设置：

await PushSDK.clearQuietHours()

权限和厂商配置

• Android 13 及以上由宿主在合适的业务时机申请通知权限。
• 厂商推送应用标识和服务端密钥在租户平台维护。
• 客户端只包含厂商要求的公开配置，不得包含服务端密钥。
• Push 服务关闭或注册失败不能阻断宿主登录。
• 重新登录或切换用户后，SDK 会使用新的公共会话重新绑定。

常见错误

登录成功但没有离线通知

依次检查：

1. 系统通知权限是否开启。
2. 当前构建是否包含目标设备厂商通道。
3. 租户平台是否启用 Push。
4. App 包名、签名和厂商控制台配置是否一致。
5. 当前用户是否关闭了离线推送或设置了免打扰。

不要在 RN 页面手工缓存 Token 作为“绑定成功”的判断依据。