跳到主要内容

标识符

searchDevices、getFeatures、getPassphraseState 以及各链方法的响应里，会出现若干个看起来都像 “ID” 的字段。这一页作为统一参考，说明每个字段到底代表什么、何时变化，以及调用 SDK 时哪些字段需要传入、哪些只用于读取。

如果你要找的是传入 SDK 的参数，例如 passphraseState、initSession、useEmptyPassphrase 等，请看 常见入参（CommonParams）。

四层标识符​

每个标识符都可以归到四类生命周期之一。知道它属于哪一层，通常就知道它什么时候该刷新、什么时候可以缓存。

层级生命周期变化触发常见字段
物理硬件跟设备本体绑定基本不变uuid、ukey_serial
传输连接当前这次连接重新 searchDevices()、切换传输方式connectId、path、name、deviceType
种子 / 钱包状态擦除、恢复、换种子之前恢复出厂、重新导入助记词、擦除设备device_id / deviceId、label
会话当前活跃会话期间自动锁屏、手动锁定、断开连接session_id、passphraseState

哪些 ID 需要你传进去？​

上面这些字段里，真正需要作为 SDK 调用入参传进去的，通常只有 3 个：connectId、deviceId、passphraseState。

ID需要传入？传在哪里什么时候需要
connectId是大多数方法的第一个位置参数基本总是需要
deviceId是链地址、签名、加解密等方法的第二个位置参数钱包级操作需要
passphraseState是params 对象里访问隐藏钱包时需要
uuid、ukey_serial、device_id、session_id、path、name、deviceType、label否只在返回值里读取不直接作为常规链方法入参

调用形态​

可以把常见方法大致理解为下面三种调用形态：

// 1. 只需要 connectId 的设备管理类方法
await ukeySdk.getFeatures(connectId);

// 2. 需要 connectId + deviceId 的钱包级方法
await ukeySdk.evmGetAddress(connectId, deviceId, params);

// 3. 隐藏钱包场景：在 params 里继续带 passphraseState
await ukeySdk.evmSignTransaction(connectId, deviceId, {
  ...params,
  passphraseState,
});

标准调用链路​

大多数接入流程都会按下面顺序使用这些标识符：

  1. 先调用 searchDevices() 拿到 connectId，必要时也可拿到 uuid、deviceType、name 等信息。
  2. 再调用 getFeatures(connectId) 读取当前设备特性，拿到 device_id、session_id、ukey_serial 等字段。
  3. 钱包级调用时，把 connectId 和 deviceId 一起传给链方法。
  4. 如果后续要持续访问同一个隐藏钱包，再额外带上 passphraseState。
const availableDevices = await ukeySdk.searchDevices();
const [{ connectId }] = availableDevices.payload;

const featureInfo = await ukeySdk.getFeatures(connectId);
const deviceId = featureInfo.payload.device_id;

await ukeySdk.evmGetAddress(connectId, deviceId, {
  path: "m/44'/60'/6'/0/2",
  useEmptyPassphrase: true,
});

隐藏钱包场景中，通常先读取一次 passphraseState，后续需要继续访问同一个隐藏钱包的调用都带上它：

const passphraseInfo = await ukeySdk.getPassphraseState(connectId);
const passphraseState = passphraseInfo.payload;

await ukeySdk.evmSignTransaction(connectId, deviceId, {
  path: "m/44'/60'/6'/0/2",
  transaction,
  passphraseState,
});

快速对照​

标识符通常来源稳定性主要用途
connectIdsearchDevices()对当前物理连接路径通常稳定把 SDK 请求路由到指定设备
uuidsearchDevices()面向展示和去重的稳定设备标识在设备列表里识别同一台物理设备
deviceIdsearchDevices() 或 getFeatures(connectId).payload.device_id重置、擦除、恢复或更换种子后可能变化在签名或派生地址前确认当前钱包
device_idgetFeatures().payload与 deviceId 是同一个值，只是固件侧命名从设备特性里读取钱包标识
session_idgetFeatures().payload设备锁定或当前会话结束后失效仅在会话仍有效时复用解锁态
passphraseStategetPassphraseState(connectId)在应用丢弃前可继续表示同一个隐藏钱包后续请求继续访问选定的隐藏钱包
ukey_serialgetFeatures().payload物理设备序列号，不代表钱包状态展示、审计或匹配物理设备

connectId 的常见格式​

不同传输方式下，connectId 的外观会不同。集成时应把它当作不透明字符串保存和回传，不要自行改写。

传输方式常见形态说明
WebUSB / bridge类似设备序列号的字符串1f6dad0b8782aab31d2f7ae2b11e5b6c
Windows 桌面 BLE12 位小写 MAC，不带冒号e4e65539cf33
Linux 桌面 BLEMAC 地址AA:BB:CC:DD:EE:FF
iOS BLECoreBluetooth UUID8F4E2C6A-1D2B-4B7F-9C2E-...

无论它长得像序列号、MAC 地址还是 UUID，都应只把它视为“SDK 当前可用的连接句柄”。

常见混淆​

connectId vs uuid​

USB 场景下，这两个值经常是同一个类似序列号的字符串。BLE 场景下，它们可能不同：

  • connectId 是 SDK 路由请求所依赖的连接句柄
  • uuid 是更适合用于展示、去重或设备记忆的稳定设备标识

结论很简单：路由始终用 connectId；如果你只是想在 UI 上稳定地识别同一台物理设备，再考虑使用 uuid。

deviceId vs uuid / ukey_serial​

  • deviceId 会在重置、擦除、恢复助记词、换种子后变化，它回答的是“这还是不是同一个钱包状态？”
  • uuid / ukey_serial 用来识别物理设备本体，它回答的是“这还是不是同一台硬件设备？”

所以链地址、签名、加解密接口依赖 deviceId，而不是依赖 uuid 或 ukey_serial。

session_id vs passphraseState​

  • session_id 表示当前这条还活着的解锁会话，设备锁屏、断开或重启后通常就失效
  • passphraseState 表示当前选中的隐藏钱包上下文，不是解锁态本身

如果多次调用之间设备锁屏了，就应该丢掉旧的 session_id，重新解锁；如果你只是想持续命中同一个隐藏钱包，则继续复用 passphraseState。

device_id（蛇形）vs deviceId（驼峰）​

它们本质上是同一个值，只是出现的上下文不同：

  • device_id 常见于 getFeatures().payload 这样的固件风格返回值
  • deviceId 常见于 searchDevices() 返回结果，以及大多数 SDK 方法签名里的驼峰写法

实际接入时，通常从 payload.device_id 里读出值，再把它当作 deviceId 传给后续方法。

使用建议​

  • 用户选定设备后，建议把 connectId 和 deviceId 成对缓存。
  • 设备重置、恢复、换种子、切换设备，或遇到 DeviceCheckDeviceIdError 后，重新调用 getFeatures(connectId) 刷新 deviceId。
  • 路由 SDK 请求时使用 connectId，不要用 uuid 代替。
  • 地址派生、交易签名、消息签名、加解密等链操作应传入 deviceId。
  • 不要把 session_id 当成长期存储，它只适合作为当前活跃会话里的短期优化。
  • passphraseState 只保留到产品流程不再需要复用同一个隐藏钱包为止。

参考​