@flatbiz/device

H5 设备信息 SDK，提供两个核心能力：

| API | 作用 | 返回值 | | --- | --- | --- | | deviceInfo | 采集设备指纹与 UA 信息 | Promise<FlatbizDevice> | | reportDeviceInfo | 采集后上报业务接口 | Promise<boolean> |

仅支持浏览器环境。非浏览器调用时：deviceInfo 返回 {}，reportDeviceInfo 返回 false。

安装

yarn add @flatbiz/device
# 或
npm i @flatbiz/device

1. deviceInfo — 采集设备信息

异步采集 H5 终端信息与 UA 解析结果，并持久化 deviceId（Cookie + localStorage，支持主域/子域共享）。

快速接入

import { deviceInfo } from '@flatbiz/device';

// 最简用法
const info = await deviceInfo();

// 推荐：由服务端下发 IP
const info2 = await deviceInfo({ ip: '203.0.113.1' });

// 自动拉取公网 IP
const info3 = await deviceInfo({ autoGetIp: true });

// 调试模式（失败时打印日志）
const info4 = await deviceInfo({ isDebug: true });

console.log(info.deviceId, info.screenSize, info.browserName);

入参 DeviceInfoOptions

全部可选。

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | ip | string | - | 自定义 IP，优先于自动获取（推荐服务端下发） | | autoGetIp | boolean | false | 为 true 时请求 https://api.ipify.org?format=json 获取公网 IP | | isDebug | boolean | false | 为 true 时在控制台输出错误信息 |

出参 FlatbizDevice

返回值为 Partial<FlatbizDeviceInfo> & Partial<FlatbizUaParserResult>。异常或非浏览器环境返回 {}。

终端字段（FlatbizDeviceInfo）

| 字段 | 类型 | 说明 | | --- | --- | --- | | ip | string | IP 地址 | | deviceId | string | 设备 ID（持久化，见下文） | | language | string | 系统语言，如 zh-CN | | screenWidth | number | 屏幕宽度（px） | | screenHeight | number | 屏幕高度（px） | | screenSize | string | 分辨率，如 390x844 | | screenDensity | number | 像素密度，如 2 | | networkType | string | 网络类型，如 wifi / 4g | | timezone | string | 时区，如 Asia/Shanghai | | timezoneOffset | number | 时区偏移（分钟） | | systemDate | string | 系统日期 | | systemTime | string | 系统时间 | | colorDepth | number | 颜色深度 | | touchSupport | string[] | 触摸支持信息 | | plugins | string[] | 浏览器插件列表 | | pluginNum | number | 插件数量 | | cookiesEnable | boolean | 是否启用 Cookie | | eventId | string | 事件 ID；仅 reportDeviceInfo 生成/重置并缓存，deviceInfo 读取当前值（未上报过时可能为空） |

UA 字段（FlatbizUaParserResult）

| 字段 | 类型 | 说明 | | --- | --- | --- | | userAgent | string | 完整 UA | | browserName | string | 浏览器名称 | | browserVersion | string | 浏览器版本 | | engineName | string | 内核名称 | | engineVersion | string | 内核版本 | | osName | string | 操作系统名称 | | osVersion | string | 操作系统版本 | | cpuModel | string | CPU 架构/型号 | | deviceType | string | UA 设备类型，如 mobile | | deviceVendor | string | 厂商 | | deviceModel | string | 型号 |

deviceId 说明（简要）

• 存储：Cookie / localStorage，Key 均为 flatbiz_device_ftbzdid
• 优先级：Cookie > localStorage > 新生成（生成后同时写入两者）
• 跨子域：Cookie 设置 domain=.注册域（如 .example.com）；localhost / IP 不设 domain
• 有效期：Cookie 约 1 天；过期后若 localStorage 仍有值会回写，ID 不变

2. reportDeviceInfo — 上报设备信息

内部先重置并缓存 eventId，再调用 deviceInfo()，按 isProd 选择上报地址 POST，将设备指纹（含 eventId）与业务埋点一并上报。请求默认 10s 超时，失败后最多再重试 2 次（网络异常 / 超时 / 408 / 429 / 5xx）。

快速接入

import {
  reportDeviceInfo,
  ReportDeviceType,
  ReportRegionType,
  ReportUserSys,
} from '@flatbiz/device';

await reportDeviceInfo({
  // 由业务侧注入；SDK 内动态计算 X-signature = md5(sortJsonStr + requestId, secretKey)
  secretKey: '联系负责人获取',
  pageName: 'publicCashier',
  orderNum: 'O20260903001',
  regionType: ReportRegionType.Overseas,
  deviceType: ReportDeviceType.H5,
  userId: 'u1',
  userSys: ReportUserSys.HopeGoo,
});

入参 ReportDeviceInfoOptions

| 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | secretKey | string | 是 | - | 鉴权密钥；SDK 计算 X-signature = md5(sortJsonStr + requestId, secretKey)；为空则不上报（不会写入上报 body） | | pageName | ReportPageName | 是 | - | 采集页面，见枚举表 | | orderNum | string | 是 | - | 项目订单号；| | regionType | ReportRegionType | 是 | - | 区域类型，见枚举表 | | deviceType | ReportDeviceType | 是 | - | 业务侧设备类型，见枚举表 | | userId | string | 否 | - | 用户 ID | | userSys | ReportUserSys | 否 | - | 会员体系，见枚举表 | | eventType | string | 否 | 'pageLoad' | pageLoad / click / 自定义 | | isProd | boolean | 否 | false | 是否生产环境；决定上报 URL | | timeout | number | 否 | 10000 | 单次请求超时（毫秒），超时后中止并按规则重试 | | retry | number | 否 | 2 | 失败后额外重试次数（共 retry + 1 次）；仅网络/超时/408/429/5xx 重试 | | retryDelay | number | 否 | 300 | 重试间隔基数（毫秒），实际等待 retryDelay * 当前尝试次数 | | isDebug | boolean | 否 | false | 失败时打印日志（不会写入上报 body） |

枚举

| 枚举 | 成员 | 值 | 说明 | | --- | --- | --- | --- | | ReportPageName | 'detail' / 'order' / 'publicCashier' / 'nativeCashier' | 同左 | 详情 / 创单 / 公共收银台 / 原生收银台 | | ReportUserSys | Tongcheng / HopeGoo / Tabigo | '01' / '02' / '03' | 同程 / HopeGoo / Tabigo | | ReportRegionType | Domestic / Overseas | '01' / '02' | 国内 / 国外 | | ReportDeviceType | PC / H5 / HopeGooApp / TabigoApp | '1' / '3' / '4' / '5' | PC / H5 / HopeGoo APP / Tabigo APP |

出参

| 类型 | 说明 | | --- | --- | | Promise<boolean> | true 上报成功；false 失败（网络/HTTP/业务 code/非浏览器等） |