推送服务（Push）

Android 离线推送由独立的 imsdk-push 提供。核心 imsdk 负责 IM 连接和消息同步，imsdk-push 负责 Token 缓存、账号绑定、重试和清理。

小米、华为、OPPO、vivo 和荣耀通过独立 Provider 模块按需接入。Provider 负责对应厂商 SDK 的初始化和 Token 获取，imsdk-push 统一负责 Token 缓存、账号绑定、重试和清理。

模块关系

宿主 App
├── chat（imsdk）
├── imsdk-push
└── imsdk-push-<vendor>（按需选择一个厂商 Provider）

imsdk-push 不依赖核心 imsdk，但与 chat 一起使用时会自动感知 IM 登录、登出和账号切换。宿主不需要传入 BimImManager，也不需要使用旧的 Push Bridge 模块。

接入前准备

开发者需要先到具体推送厂商的控制台申请并配置应用凭据：

• 小米：申请 AppId 和 AppKey，并确保应用包名、签名证书与小米控制台配置一致。
• 华为：在 AppGallery Connect 创建应用，配置包名和签名指纹，并下载 agconnect-services.json。
• OPPO：开通 OPPO PUSH，按当前客户端 SDK 要求准备 AppKey 和 AppSecret。
• vivo：开通 vivo 消息推送，准备 AppId 和 ApiKey。
• 荣耀：开通 HONOR Push，准备 AppId；使用 mcs-services.json 时还需要按荣耀文档配置插件。

厂商配置、包名和签名不匹配时，Token 获取或通知送达可能失败。用于服务端鉴权和消息下发的 MasterSecret、ClientSecret 等凭据不能写入 Android 工程或 APK。OPPO 客户端注册参数以所用 OPPO Push SDK 版本的官方文档为准，不要混用服务端 MasterSecret。

Gradle 依赖

所有 IMSDK 模块使用同一版本。基础接入至少声明核心和 Push 基础模块：

dependencies {
    implementation("com.beework.im:chat:<version>")
    implementation("com.beework.im:imsdk-push:<version>")
}

按设备渠道选择一个厂商 Provider：

dependencies {
    implementation("com.beework.im:imsdk-push-xiaomi:<version>")
    // implementation("com.beework.im:imsdk-push-huawei:<version>")
    // implementation("com.beework.im:imsdk-push-oppo:<version>")
    // implementation("com.beework.im:imsdk-push-vivo:<version>")
    // implementation("com.beework.im:imsdk-push-honor:<version>")
}

没有使用的厂商模块不要引入，否则对应厂商 SDK 和 Manifest 组件也会进入宿主构建产物。

初始化 Push

建议在 Application.onCreate() 中、隐私授权和厂商配置完成后显式注册：

val push = BimPushManager.getInstance().registerPush(
    context = applicationContext,
    config = XiaomiPushConfig(
        appId = "<xiaomi-app-id>",
        appKey = "<xiaomi-app-key>",
    ),
)

也可以使用厂商模块提供的便捷入口：

XiaomiPush.register(
    context = applicationContext,
    appId = "<xiaomi-app-id>",
    appKey = "<xiaomi-app-key>",
)

autoRegister 默认开启。传入 false 时只初始化 Provider，不自动请求 Token；宿主仍可通过 Provider 或 Push Manager 的公开能力触发后续操作。

Push 状态与点击事件

val manager = BimPushManager.getInstance()

val status = manager.getStatus(BimPushProvider.XIAOMI)
val diagnostic = manager.getDiagnostic(BimPushProvider.XIAOMI)

manager.addPushClickListener { event ->
    // 根据 event.uri 和 event.extras 跳转到业务页面
}

BimPushStatus 用于表达 NOT_CONFIGURED、INITIALIZING、TOKEN_CACHED、SYNCING、SYNCED 和 FAILED 等状态；BimPushDiagnostic 只提供状态、是否有 Token 和脱敏错误信息。

各厂商 Provider 会将通知点击事件转换为 BimPushClickEvent。SDK 内部拥有统一点击路由组件，宿主只负责业务页面路由，不需要声明厂商专用 Scheme。Push SDK 不替宿主实现业务页面。

生命周期与错误边界

• 与 chat 同进程使用时，IM 登录成功后 Push 自动绑定当前账号和设备会话；登出或认证失效时清理当前账号的服务端 Push 设置。
• Push 初始化、Token 获取、网络同步或清理失败不会阻断 IM 初始化、登录和消息收发。
• 账号切换时，旧账号的 Token 不会继承到新账号；Token 更新、去重、重试和清理由 imsdk-push 负责。
• 宿主销毁 Push runtime 时调用 BimPushManager.getInstance().release()。

公开基础接口

class BimPushManager : BimPushService {
    fun registerPush(
        context: Context,
        config: BimPushConfig,
        autoRegister: Boolean = true,
    ): BimPushManager

    suspend fun reportToken(token: BimPushToken)
    suspend fun clearToken(provider: BimPushProvider)
    fun getStatus(provider: BimPushProvider): BimPushStatus
    fun getDiagnostic(provider: BimPushProvider): BimPushDiagnostic
    fun addListener(listener: BimPushListener)
    fun removeListener(listener: BimPushListener)
    fun addPushClickListener(listener: BimPushClickListener)
    fun removePushClickListener(listener: BimPushClickListener)
    fun release()
}

reportToken 适用于自定义厂商或宿主已有推送通道的场景。标准厂商接入优先使用对应 Provider 模块。详细配置见：

• 小米 Push
• 华为 Push
• OPPO Push
• vivo Push
• 荣耀 Push