Bridge communication protocol

Bridge is the message layer between mini-sdk and the host environment (simulator / native app). All API calls ultimately go through the Bridge.

Architecture overview

┌──────────────┐    Transport     ┌──────────────────┐
│   mini-sdk   │ ◄──────────────► │  Host            │
│              │   send/onMessage │  Sim. / Native    │
│  bridge.call │ ──── req ──────► │                   │
│              │ ◄─── ack ─────── │  Ack received     │
│              │ ◄─── res ─────── │  Return result    │
│  bridge.on   │ ◄─── evt ─────── │  Push events      │
└──────────────┘                  └──────────────────┘

Message kinds (BridgeKind)

Bridge supports five message kinds:

Kind	Direction	Description
req	SDK → Host	Request call, carries type + name + payload
res	Host → SDK	Response, carries result or error
ack	Host → SDK	Acknowledgement, used for long-running interactive operations (SSO, biometrics, etc.)
evt	Host → SDK	Event push (lifecycle, route changes, etc.)
chunk	Host → SDK	Streamed data chunks (large file transfer, etc.)

BridgeEnvelope message format

Each message is wrapped in a single envelope:

interface BridgeEnvelope<P = unknown, R = unknown> {
  v: number          // 协议版本（当前为 1）
  id?: number        // 请求序列号（req/res/ack/chunk 共享）
  kind: BridgeKind   // 消息类型
  type: BridgeType   // API 分类（Router / UI / Network 等）
  name: string       // 完整方法名，格式 "Type.methodName"
  ts?: number        // 时间戳
  payload?: P        // 请求参数
  result?: R         // 响应结果
  error?: BridgeError // 错误信息
}

Bridge class

Bridge is the core communication class; the SDK default-exports a singleton bridge:

import { bridge, Bridge } from 'mini-sdk'

Constructor options

const customBridge = new Bridge({
  defaultTimeout: 10000,    // 默认超时 10s
  defaultAckTimeout: 300000, // ACK 后超时 5min（用于交互操作）
  debug: false,              // 是否打印调试日志
})

bridge.call() — send a request

bridge.call<P, R>(
  type: BridgeType,   // API 分类
  name: string,       // 方法名
  payload?: P,        // 参数
  timeout?: number,   // 超时时间（ms），0 = 不超时
  onChunk?: (chunk: unknown) => void  // 流式回调
): Promise<R>

Example:

// 简单调用
const result = await bridge.call('Storage', 'get', { key: 'token' })

// 不超时（交互类操作）
const dialogResult = await bridge.call('UI', 'showDialog', {
  title: '提示',
  content: '确认删除？',
}, 0) // timeout = 0，等待用户操作

bridge.on() — subscribe to events

const unsubscribe = bridge.on<P>(
  type: BridgeType,
  name: string,
  handler: (payload: P, envelope: BridgeEnvelope<P>) => void
): () => void  // 返回取消订阅函数

Example:

// 监听生命周期事件
const unsub = bridge.on('Lifecycle', 'show', (payload) => {
  console.log('页面显示')
})

// 取消监听
unsub()

bridge.destroy() — destroy

bridge.destroy()

On destroy, the Bridge will:

1. Clear all timeout timers
2. Reject all pending requests with a BridgeDestroyed error
3. Remove all event listeners
4. Release the Transport connection

BridgeType categories

type BridgeType =
  | 'System'      // 系统握手
  | 'Router'      // 路由导航
  | 'UI'          // 界面交互
  | 'Network'     // 网络请求
  | 'Lifecycle'   // 页面生命周期
  | 'Storage'     // 数据存储
  | 'Clipboard'   // 剪贴板
  | 'Device'      // 设备能力
  | 'Auth'        // 认证鉴权
  | 'Analytics'   // 数据分析
  | 'Wallet'      // 钱包支付
  | 'Notification' // 通知推送
  | 'Vehicle'     // 车辆信息
  | 'Component'   // 组件操控
  | (string & {}) // 可扩展

Transport layer

Transport is responsible for actual message delivery; the implementation is selected automatically for the environment:

Environment	Transport implementation	Channel
Simulator	SimulatorTransport	window.__MINIDEV__ IPC
iOS	NativeTransport	webkit.messageHandlers.MiniAppBridge
Android	NativeTransport	MiniAppBridge Java bridge

import { createTransport } from 'mini-sdk'
const transport = createTransport() // 自动检测环境

Handshake

At SDK init, a handshake with the host is completed via woo.hello():

// 自动调用，一般无需手动触发
await woo.hello()

Handshake flow:

1. The SDK sends a System.hello request with SUPPORTED_PROTOCOL = 1
2. The host returns { role, protocol } to confirm the protocol version
3. If the protocol version does not match, the SDK logs a warning and does not block
4. A default error handler is also registered (unhandled errors are shown via Toast)