t-comm
Version:
专业、稳定、纯粹的工具库
87 lines (86 loc) • 3.81 kB
TypeScript
/**
* 蓝牙"碰一碰"对外类型定义
*/
/** 扫描到的蓝牙设备（仅声明用得到的字段，避免污染） */
export interface BluetoothDeviceInfo {
deviceId: string;
RSSI: number;
name?: string;
localName?: string;
advertisData?: ArrayBuffer;
advertisServiceUUIDs?: string[];
serviceData?: Record<string, ArrayBuffer>;
[key: string]: any;
}
/** 启动失败时通过 onError 抛出的错误信息 */
export interface BluetoothBumpError {
errCode?: number;
errMsg?: string;
raw?: any;
}
/**
* 匹配模式：
* - 'simple' ：默认行为。扫到对方且 RSSI 达标即触发（单向发现，简单快速）。
* - 'mutual' ：前端自撮合。双向互认后才触发：
* 我广播里带"我看到的对方 ID"，对方广播里也带"它看到的对方 ID"；
* 当双方广播里携带的 peerId 都指向对方时，才算配对成功。
*/
export type BluetoothBumpMode = 'simple' | 'mutual';
/** 广播载荷（mutual 模式）：固定长度 13 字节，myTempId|seenPeerId */
export interface BluetoothBumpPayload {
/** 发送端自己的临时 ID（6 位大写） */
myTempId: string;
/** 发送端当前"看到的对方 ID"，未看到时为 '------' */
seenPeerId: string;
}
/** BluetoothBump 构造选项 */
export interface BluetoothBumpOptions {
/** 服务 UUID，两端必须一致 */
serviceUuid?: string;
/** 特征 UUID（仅外围模式使用） */
characteristicUuid?: string;
/** RSSI 阈值，超过此值视为"碰到了" */
rssiThreshold?: number;
/** 同一设备的去重冷却时间 */
cooldownMs?: number;
/** 成功触发后保持广播的时长（让对方也能扫到自己） */
lingerBeforeStopMs?: number;
/** iOS 兜底轮询间隔 */
pollIntervalMs?: number;
/** 隐私协议弹窗内容（不传用默认文案） */
privacyContent?: string;
/**
* 匹配模式，默认 'simple'（保持向后兼容）。
* 选 'mutual' 开启前端自撮合（双向互认后才触发 onBump）。
*/
mode?: BluetoothBumpMode;
/** mutual 模式：候选 peer 信息的有效期（毫秒），过期则从候选池移除 */
peerTtlMs?: number;
/** mutual 模式：更新自己广播里 seenPeerId 的最小间隔（毫秒），防抖 */
advertiseUpdateThrottleMs?: number;
/**
* 业务回调：碰到对方时触发
* - peerDeviceId：扫描层的设备地址（iOS 是本机视角的 UUID，Android 是 MAC）。
* ⚠️ 这个值是"扫描者本地"视角的，A 拿到的对方 deviceId 与 B 自己的 deviceId 不一定相同，
* 不能用它跟对方的 myTempId 直接对比。
* - peerTempId：对方写在广播 payload 里的 myTempId（6 位字符串）。
* 这个值是"对方应用层产生的"，A 看到的 peerTempId 与 B 的 myTempId **一定一致**，
* 适合两台手机做配对核对（"我方 ID" vs "对方 ID"）。
* 若对方广播解析失败则为空字符串。
*/
onBump?: (peerDeviceId: string, rssi: number, dev: BluetoothDeviceInfo, peerTempId: string) => void;
/** 业务回调：启动失败时触发 */
onError?: (err: BluetoothBumpError) => void;
/** 业务回调：日志/状态变化（用于打日志或 UI 更新） */
onLog?: (msg: string, data?: any) => void;
/** 业务回调：每次扫到设备（不论是否碰到）时触发，用于调试/UI 展示 */
onDeviceFound?: (dev: BluetoothDeviceInfo) => void;
}
/** 触发碰一碰的判定参数（纯函数 shouldTriggerBump 使用） */
export interface ShouldTriggerBumpParams {
rssi: number;
threshold: number;
lastBumpTime: number;
now: number;
cooldownMs: number;
}