Bridge 进阶

本页面向 App 宿主维护者，以及需要接入已有 DSBridge SDK 的业务。基本调用、事件监听和错误处理见 Bridge 指南。以下协议仅适用于默认 App adapter；自定义 adapter 返回已解码数据。

传输通道与方法签名

默认传输支持 Android _dsbridge.call 和带 App 标识的 iOS prompt 通道。调用可接收有效同步回包或等待异步回调；异步操作需要 Native 返回完成回包，否则等待超时。Android 的异步占位回包为 code=-1 且没有 data，iOS 的占位回包额外带 data=""；两者都会继续等待完成回调。prompt 通道在业务调用前通过 _dsb.hasNativeMethod 查询签名，优先异步，否则使用同步签名；业务方法只执行一次，失败不会切换签名重试。查询失败或方法不存在时明确报 transport 错误。本库的 call 是一次请求一次结果，不提供 DSBridge progress 多次回调语义。

App 回包解码

默认 adapter 解开 DSBridge 传输外壳，再解析 App 的 code / ok / data 协议：成功码为 0、200、"0"、"200"，boolean ok 优先。支持 JSON 对象字符串、response 外壳及 JSON 字符串 data。只解码一次协议，不重新解释业务 data 中的 code / ok 字段。

例如，App 回包 { code: 0, data: { code: 42, title: 'Document' } } 的业务结果为 { code: 42, title: 'Document' }，内层 code 不会再次被当成状态码。宿主失败通过 BridgeError 表达，业务码保存在 hostCode。

Native 事件与 SDK 共存

Native 事件沿用 DSBridge 的方法名和参数数组，数组的第一个参数作为事件 payload；对象或数组 JSON 字符串会被解析。每个事件可以有多个监听者，跨 Bridge 实例共享底层分发入口。每次 on 都返回独立订阅，dispose 幂等，释放后不再交付该监听者。已有 SDK 方法（包括类原型上的命名空间方法）会触发订阅冲突；SDK 后续注册同名方法时保留其处理和应答。外部分发包装保留各自的原处理器，同一消息不重复交付监听者，最后释放时保留外部处理链。

默认事件适配不会改写 SDK 的 JS 方法注册表。与已注册方法同名的订阅会报错；其它消息转交页面原有分发器。后加载 SDK 对分发入口的普通赋值也会保留，最后一个监听者释放时恢复原有或后安装的分发器；没有原有分发器时移除本库入口。不可安全组合的入口会显式报错。

业务应在页面卸载或不再需要事件时调用 subscription.dispose()。多个订阅独立释放；不要通过覆盖底层分发入口来清理本库监听。

自定义 adapter 的边界

• call(method, payload, options) 返回 Promise<unknown>，成功值是已解码数据，失败通过 throw / reject 表达。
• on(event, handler) 返回清理函数或 { dispose() }，不能返回 void；清理必须实际停止该订阅。
• 自定义事件 payload 不会被库自动解析。类型表只提供静态约束，adapter 或业务需要验证外部数据。
• 基础方法仍调用 configAction、goBack、closePage 对应的方法名，并验证已声明的配置或关闭结果字段。
• 实例创建时捕获 adapter 方法并保留 receiver；修改原配置中的方法不会替换实例行为，adapter 自己的内部状态仍可变化。

可先用 浏览器 mock 示例 验证业务流程，再在目标 Android / iOS WebView 中验证签名、异步完成回包、超时和事件释放。浏览器 mock 不能验证真实 Native 通道。