@flatbiz/device 2.0.2 → 2.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +132 -69
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,103 +1,166 @@
|
|
|
1
|
-
|
|
1
|
+
# @flatbiz/device
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
H5 设备信息 SDK，提供两个核心能力：
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
| API | 作用 | 返回值 |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| `deviceInfo` | 采集设备指纹与 UA 信息 | `Promise<FlatbizDevice>` |
|
|
8
|
+
| `reportDeviceInfo` | 采集后上报业务接口 | `Promise<boolean>` |
|
|
6
9
|
|
|
7
|
-
|
|
8
|
-
- **移除 `utils` 模块**：`getDeviceId` 统一从 `helper-get-deviceId` 导出，不再通过 `src/utils.ts`
|
|
10
|
+
> 仅支持浏览器环境。非浏览器调用时：`deviceInfo` 返回 `{}`，`reportDeviceInfo` 返回 `false`。
|
|
9
11
|
|
|
10
|
-
|
|
12
|
+
---
|
|
11
13
|
|
|
12
|
-
|
|
13
|
-
- **`ip`**：传入服务端下发的 IP，优先于自动获取
|
|
14
|
-
- **`autoGetIp`**：为 `true` 时通过 `https://api.ipify.org?format=json` 拉取公网 IP（默认 `false`）
|
|
15
|
-
- **`isDebug`**：为 `true` 时在控制台输出非浏览器环境或解析失败等错误信息（默认 `false`）
|
|
16
|
-
- 新增返回字段 **`ip`**、**`screenSize`**（格式 `{width}x{height}`，如 `390x844`）
|
|
17
|
-
- 非浏览器环境（`typeof window === 'undefined'`）安全返回 `{}`，避免 SSR/Node 直接调用抛错
|
|
18
|
-
- 新增 helpers：`getIp`、`getWindowSize`；`getDeviceId` 独立为 `helper-get-deviceId`
|
|
19
|
-
- **`deviceId` 持久化**：基于 `js-cookie` 写入可跨子域共享的 cookie，并与 localStorage 双向同步
|
|
20
|
-
- 开发体验：补充 Vitest 单元测试（含 jsdom 主域/子域 cookie 共享用例）；`yarn demo`（Vite）可本地预览 `public/index.html`
|
|
14
|
+
## 安装
|
|
21
15
|
|
|
22
|
-
|
|
16
|
+
```bash
|
|
17
|
+
yarn add @flatbiz/device
|
|
18
|
+
# 或
|
|
19
|
+
npm i @flatbiz/device
|
|
20
|
+
```
|
|
23
21
|
|
|
24
|
-
|
|
22
|
+
---
|
|
25
23
|
|
|
26
|
-
|
|
27
|
-
- `screenWidth`、`screenHeight`、`screenSize`、`screenDensity`
|
|
28
|
-
- `networkType`、`timezone`、`timezoneOffset`、`systemDate`、`systemTime`
|
|
29
|
-
- `colorDepth`、`touchSupport`、`plugins`、`pluginNum`、`cookiesEnable`
|
|
24
|
+
## 1. `deviceInfo` — 采集设备信息
|
|
30
25
|
|
|
31
|
-
|
|
26
|
+
异步采集 H5 终端信息与 UA 解析结果，并持久化 `deviceId`（Cookie + localStorage，支持主域/子域共享）。
|
|
32
27
|
|
|
33
|
-
|
|
34
|
-
- `engineName`、`engineVersion`
|
|
35
|
-
- `osName`、`osVersion`、`cpuModel`
|
|
36
|
-
- `deviceType`、`deviceVendor`、`deviceModel`
|
|
28
|
+
### 快速接入
|
|
37
29
|
|
|
38
|
-
|
|
30
|
+
```ts
|
|
31
|
+
import { deviceInfo } from '@flatbiz/device';
|
|
39
32
|
|
|
40
|
-
|
|
33
|
+
// 最简用法
|
|
34
|
+
const info = await deviceInfo();
|
|
41
35
|
|
|
42
|
-
|
|
36
|
+
// 推荐：由服务端下发 IP
|
|
37
|
+
const info2 = await deviceInfo({ ip: '203.0.113.1' });
|
|
43
38
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
| Cookie | `flatbiz_device_ftbzdid` | 优先读取；用于跨子域共享 |
|
|
47
|
-
| localStorage | `flatbiz_device_ftbzdid` | Cookie 缺失时的回退；Cookie 有值时会被覆盖 |
|
|
39
|
+
// 自动拉取公网 IP
|
|
40
|
+
const info3 = await deviceInfo({ autoGetIp: true });
|
|
48
41
|
|
|
49
|
-
|
|
42
|
+
// 调试模式（失败时打印日志）
|
|
43
|
+
const info4 = await deviceInfo({ isDebug: true });
|
|
50
44
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
3. **都没有**：生成新 ID（16 位类 UUID），同时写入 Cookie 与 localStorage
|
|
45
|
+
console.log(info.deviceId, info.screenSize, info.browserName);
|
|
46
|
+
```
|
|
54
47
|
|
|
55
|
-
|
|
48
|
+
### 入参 `DeviceInfoOptions`
|
|
56
49
|
|
|
57
|
-
|
|
50
|
+
全部可选。
|
|
58
51
|
|
|
59
|
-
|
|
|
60
|
-
| --- | --- | --- |
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `domain` | 见下 | 主域与子域共享 |
|
|
52
|
+
| 参数 | 类型 | 默认值 | 说明 |
|
|
53
|
+
| --- | --- | --- | --- |
|
|
54
|
+
| `ip` | `string` | - | 自定义 IP，优先于自动获取（推荐服务端下发） |
|
|
55
|
+
| `autoGetIp` | `boolean` | `false` | 为 `true` 时请求 `https://api.ipify.org?format=json` 获取公网 IP |
|
|
56
|
+
| `isDebug` | `boolean` | `false` | 为 `true` 时在控制台输出错误信息 |
|
|
65
57
|
|
|
66
|
-
|
|
58
|
+
### 出参 `FlatbizDevice`
|
|
67
59
|
|
|
68
|
-
|
|
60
|
+
返回值为 `Partial<FlatbizDeviceInfo> & Partial<FlatbizUaParserResult>`。异常或非浏览器环境返回 `{}`。
|
|
69
61
|
|
|
70
|
-
|
|
71
|
-
- `www.example.com` → `domain=.example.com`
|
|
72
|
-
- `api.example.com` → `domain=.example.com`
|
|
62
|
+
#### 终端字段（`FlatbizDeviceInfo`）
|
|
73
63
|
|
|
74
|
-
|
|
64
|
+
| 字段 | 类型 | 说明 |
|
|
65
|
+
| --- | --- | --- |
|
|
66
|
+
| `ip` | `string` | IP 地址 |
|
|
67
|
+
| `deviceId` | `string` | 设备 ID（持久化，见下文） |
|
|
68
|
+
| `language` | `string` | 系统语言，如 `zh-CN` |
|
|
69
|
+
| `screenWidth` | `number` | 屏幕宽度（px） |
|
|
70
|
+
| `screenHeight` | `number` | 屏幕高度（px） |
|
|
71
|
+
| `screenSize` | `string` | 分辨率，如 `390x844` |
|
|
72
|
+
| `screenDensity` | `number` | 像素密度，如 `2` |
|
|
73
|
+
| `networkType` | `string` | 网络类型，如 `wifi` / `4g` |
|
|
74
|
+
| `timezone` | `string` | 时区，如 `Asia/Shanghai` |
|
|
75
|
+
| `timezoneOffset` | `number` | 时区偏移（分钟） |
|
|
76
|
+
| `systemDate` | `string` | 系统日期 |
|
|
77
|
+
| `systemTime` | `string` | 系统时间 |
|
|
78
|
+
| `colorDepth` | `number` | 颜色深度 |
|
|
79
|
+
| `touchSupport` | `string[]` | 触摸支持信息 |
|
|
80
|
+
| `plugins` | `string[]` | 浏览器插件列表 |
|
|
81
|
+
| `pluginNum` | `number` | 插件数量 |
|
|
82
|
+
| `cookiesEnable` | `boolean` | 是否启用 Cookie |
|
|
83
|
+
| `eventId` | `string` | 事件 ID；仅 `reportDeviceInfo` 生成/重置并缓存，`deviceInfo` 读取当前值（未上报过时可能为空） |
|
|
84
|
+
|
|
85
|
+
#### UA 字段（`FlatbizUaParserResult`）
|
|
86
|
+
|
|
87
|
+
| 字段 | 类型 | 说明 |
|
|
88
|
+
| --- | --- | --- |
|
|
89
|
+
| `userAgent` | `string` | 完整 UA |
|
|
90
|
+
| `browserName` | `string` | 浏览器名称 |
|
|
91
|
+
| `browserVersion` | `string` | 浏览器版本 |
|
|
92
|
+
| `engineName` | `string` | 内核名称 |
|
|
93
|
+
| `engineVersion` | `string` | 内核版本 |
|
|
94
|
+
| `osName` | `string` | 操作系统名称 |
|
|
95
|
+
| `osVersion` | `string` | 操作系统版本 |
|
|
96
|
+
| `cpuModel` | `string` | CPU 架构/型号 |
|
|
97
|
+
| `deviceType` | `string` | UA 设备类型，如 `mobile` |
|
|
98
|
+
| `deviceVendor` | `string` | 厂商 |
|
|
99
|
+
| `deviceModel` | `string` | 型号 |
|
|
75
100
|
|
|
76
|
-
|
|
101
|
+
### `deviceId` 说明（简要）
|
|
77
102
|
|
|
78
|
-
- `
|
|
79
|
-
-
|
|
80
|
-
-
|
|
103
|
+
- **存储**：Cookie / localStorage，Key 均为 `flatbiz_device_ftbzdid`
|
|
104
|
+
- **优先级**：Cookie > localStorage > 新生成（生成后同时写入两者）
|
|
105
|
+
- **跨子域**：Cookie 设置 `domain=.注册域`（如 `.example.com`）；`localhost` / IP 不设 domain
|
|
106
|
+
- **有效期**：Cookie 约 1 天；过期后若 localStorage 仍有值会回写，**ID 不变**
|
|
81
107
|
|
|
82
|
-
|
|
108
|
+
---
|
|
83
109
|
|
|
84
|
-
|
|
85
|
-
- Cookie 约 24 小时过期后，若 localStorage 仍有值，会按优先级回写新 Cookie，**ID 保持不变**
|
|
110
|
+
## 2. `reportDeviceInfo` — 上报设备信息
|
|
86
111
|
|
|
87
|
-
|
|
112
|
+
内部先重置并缓存 `eventId`，再调用 `deviceInfo()`，按 `isProd` 选择上报地址 `POST`，将设备指纹（含 `eventId`）与业务埋点一并上报。
|
|
113
|
+
|
|
114
|
+
### 快速接入
|
|
88
115
|
|
|
89
116
|
```ts
|
|
90
|
-
import {
|
|
117
|
+
import {
|
|
118
|
+
reportDeviceInfo,
|
|
119
|
+
ReportDeviceType,
|
|
120
|
+
ReportRegionType,
|
|
121
|
+
ReportUserSys,
|
|
122
|
+
} from '@flatbiz/device';
|
|
123
|
+
|
|
124
|
+
await reportDeviceInfo({
|
|
125
|
+
// 由业务侧注入
|
|
126
|
+
signature: '联系负责人获取',
|
|
127
|
+
pageName: 'publicCashier',
|
|
128
|
+
orderNum: 'O20260903001',
|
|
129
|
+
regionType: ReportRegionType.Overseas,
|
|
130
|
+
deviceType: ReportDeviceType.H5,
|
|
131
|
+
userId: 'u1',
|
|
132
|
+
userSys: ReportUserSys.HopeGoo,
|
|
133
|
+
});
|
|
91
134
|
|
|
92
|
-
|
|
93
|
-
const info = await deviceInfo({ ip: '203.0.113.1' });
|
|
135
|
+
```
|
|
94
136
|
|
|
95
|
-
|
|
96
|
-
const info2 = await deviceInfo({ autoGetIp: true });
|
|
137
|
+
### 入参 `ReportDeviceInfoOptions`
|
|
97
138
|
|
|
98
|
-
|
|
99
|
-
|
|
139
|
+
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
|
140
|
+
| --- | --- | --- | --- | --- |
|
|
141
|
+
| `signature` | `string` | 是 | - | 鉴权签名，写入 `X-signature`；为空会 `console.error`（不会写入上报 body） |
|
|
142
|
+
| `pageName` | `ReportPageName` | 是 | - | 采集页面，见枚举表 |
|
|
143
|
+
| `orderNum` | `string` | 是 | - | 项目订单号；|
|
|
144
|
+
| `regionType` | `ReportRegionType` | 是 | - | 区域类型，见枚举表 |
|
|
145
|
+
| `deviceType` | `ReportDeviceType` | 是 | - | 业务侧设备类型，见枚举表 |
|
|
146
|
+
| `userId` | `string` | 否 | - | 用户 ID |
|
|
147
|
+
| `userSys` | `ReportUserSys` | 否 | - | 会员体系，见枚举表 |
|
|
148
|
+
| `eventType` | `string` | 否 | `'pageLoad'` | `pageLoad` / `click` / 自定义 |
|
|
149
|
+
| `isProd` | `boolean` | 否 | `true` | 是否生产环境；决定上报 URL |
|
|
150
|
+
| `isDebug` | `boolean` | 否 | `false` | 失败时打印日志（不会写入上报 body） |
|
|
151
|
+
|
|
152
|
+
#### 枚举
|
|
153
|
+
|
|
154
|
+
| 枚举 | 成员 | 值 | 说明 |
|
|
155
|
+
| --- | --- | --- | --- |
|
|
156
|
+
| `ReportPageName` | `'detail'` / `'order'` / `'publicCashier'` / `'nativeCashier'` | 同左 | 详情 / 创单 / 公共收银台 / 原生收银台 |
|
|
157
|
+
| `ReportUserSys` | `Tongcheng` / `HopeGoo` / `Tabigo` | `'01'` / `'02'` / `'03'` | 同程 / HopeGoo / Tabigo |
|
|
158
|
+
| `ReportRegionType` | `Domestic` / `Overseas` | `'01'` / `'02'` | 国内 / 国外 |
|
|
159
|
+
| `ReportDeviceType` | `PC` / `H5` / `HopeGooApp` / `TabigoApp` | `'1'` / `'3'` / `'4'` / `'5'` | PC / H5 / HopeGoo APP / Tabigo APP |
|
|
160
|
+
|
|
161
|
+
### 出参
|
|
162
|
+
|
|
163
|
+
| 类型 | 说明 |
|
|
164
|
+
| --- | --- |
|
|
165
|
+
| `Promise<boolean>` | `true` 上报成功；`false` 失败（网络/HTTP/业务 code/非浏览器等） |
|
|
100
166
|
|
|
101
|
-
// deviceId 已持久化在 cookie / localStorage
|
|
102
|
-
console.log(info.deviceId);
|
|
103
|
-
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@flatbiz/device",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.4",
|
|
4
4
|
"homepage": "https://gitlab.itcjf.com/flatjs/flat-biz-devkit",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -39,7 +39,7 @@
|
|
|
39
39
|
"dev": "vite"
|
|
40
40
|
},
|
|
41
41
|
"dependencies": {
|
|
42
|
-
"js-cookie": "3.0.
|
|
42
|
+
"js-cookie": "3.0.1",
|
|
43
43
|
"psl": "1.15.0",
|
|
44
44
|
"ua-parser-js": "2.0.9"
|
|
45
45
|
},
|
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
"vitest": "4.1.6"
|
|
57
57
|
},
|
|
58
58
|
"engines": {
|
|
59
|
-
"node": ">=
|
|
59
|
+
"node": ">=12.0.0"
|
|
60
60
|
},
|
|
61
61
|
"publishConfig": {
|
|
62
62
|
"access": "public",
|