@flatbiz/device 2.0.0 → 2.0.1

package/README.md

@@ -1,6 +1,6 @@
 ## @flatbiz/device
 
-增强 H5 设备信息采集能力：`deviceInfo` 支持自定义/自动获取 IP、屏幕分辨率字符串，并合并 UA 解析结果；补充 Vitest 单测与 Vite 本地演示。
+增强 H5 设备信息采集能力：`deviceInfo` 支持自定义/自动获取 IP、屏幕分辨率字符串，并合并 UA 解析结果；`deviceId` 通过 cookie + localStorage 持久化，并支持主域与子域共享。
 
 ### Breaking Changes
 
@@ -16,7 +16,8 @@
 - 新增返回字段 **`ip`**、**`screenSize`**（格式 `{width}x{height}`，如 `390x844`）
 - 非浏览器环境（`typeof window === 'undefined'`）安全返回 `{}`，避免 SSR/Node 直接调用抛错
 - 新增 helpers：`getIp`、`getWindowSize`；`getDeviceId` 独立为 `helper-get-deviceId`
-- 开发体验：补充 Vitest 单元测试；`yarn demo`（Vite）可本地预览 `public/index.html`
+- **`deviceId` 持久化**：基于 `js-cookie` 写入可跨子域共享的 cookie，并与 localStorage 双向同步
+- 开发体验：补充 Vitest 单元测试（含 jsdom 主域/子域 cookie 共享用例）；`yarn demo`（Vite）可本地预览 `public/index.html`
 
 ### `deviceInfo()` 返回字段
 
@@ -34,6 +35,55 @@
 - `osName`、`osVersion`、`cpuModel`
 - `deviceType`、`deviceVendor`、`deviceModel`
 
+### deviceId 与 Cookie
+
+`deviceInfo()` 内部会调用 `getDeviceId()` 生成/读取设备 ID。存储与同步规则如下。
+
+#### 存储键
+
+| 介质 | Key | 说明 |
+| --- | --- | --- |
+| Cookie | `flatbiz_device_ftbzdid` | 优先读取；用于跨子域共享 |
+| localStorage | `flatbiz_device_ftbzdid` | Cookie 缺失时的回退；Cookie 有值时会被覆盖 |
+
+#### 读取优先级
+
+1. **Cookie 有值**：返回该 ID，并写入/覆盖 localStorage
+2. **Cookie 无、localStorage 有**：返回 localStorage 中的 ID，并回写 Cookie
+3. **都没有**：生成新 ID（16 位类 UUID），同时写入 Cookie 与 localStorage
+
+#### Cookie 属性
+
+通过 `js-cookie` 写入，默认属性：
+
+| 属性 | 值 | 说明 |
+| --- | --- | --- |
+| `expires` | `1`（约 1 天） | 过期后续访问会重新走生成/回写逻辑 |
+| `path` | `/` | 整站路径可访问 |
+| `sameSite` | `Lax` | 常规同站导航可携带 |
+| `domain` | 见下 | 主域与子域共享 |
+
+#### 跨子域共享（`domain`）
+
+使用 [psl](https://www.npmjs.com/package/psl) 解析当前 `location.hostname` 的注册域，并设置为带前缀点的根域，例如：
+
+- `example.com` → `domain=.example.com`
+- `www.example.com` → `domain=.example.com`
+- `api.example.com` → `domain=.example.com`
+
+因此在同一注册域下，主域与各子域可共享同一个 `deviceId`（localStorage 仍按源隔离，跨域依赖 Cookie）。
+
+以下场景**不设置** `domain`（仅当前 host 生效）：
+
+- `localhost`
+- IP 地址（如 `127.0.0.1`）
+- 无法解析出注册域的 hostname
+
+#### 注意事项
+
+- 浏览器禁用 Cookie 时，仍可能依赖 localStorage；返回字段 `cookiesEnable` 可反映 Cookie 是否启用
+- Cookie 约 24 小时过期后，若 localStorage 仍有值，会按优先级回写新 Cookie，**ID 保持不变**
+
 ### Usage
 
 ```ts
@@ -47,4 +97,7 @@ const info2 = await deviceInfo({ autoGetIp: true });
 
 // 调试模式
 const info3 = await deviceInfo({ isDebug: true });
+
+// deviceId 已持久化在 cookie / localStorage
+console.log(info.deviceId);
 ```

package/dist/helpers/helper-get-deviceId.d.ts

@@ -1,7 +1,8 @@
 /**
  * 获取设备 ID
- * @returns 设备 ID
- * - 如果设备 ID 不存在，则生成一个设备 ID 并返回
- * - 如果设备 ID 存在，则返回设备 ID
+ * 优先级：cookie > localStorage > 新生成
+ * - cookie 有值：返回并覆盖 localStorage
+ * - cookie 无、localStorage 有：返回并回写 cookie（含子域名可共享的 domain）
+ * - 都没有：生成新 ID，同时写入 cookie 与 localStorage
  */
 export declare const getDeviceId: () => string;

package/dist/helpers/helper-get-deviceId.js

@@ -1,4 +1,8 @@
+import Cookies from 'js-cookie';
+import psl from 'psl';
 const storageKey = 'flatbiz_device';
+const cacheKey = 'ftbzdid';
+const cookieName = `${storageKey}_${cacheKey}`;
 const localStorageCache = {
     set: (key, value) => {
         localStorage.setItem(`${storageKey}_${key}`, value);
@@ -16,19 +20,46 @@ const getUuid = () => {
         return v.toString(16);
     });
 };
+/** 获取可用于子域名共享的 cookie domain（如 .example.com） */
+const getCookieDomain = () => {
+    const hostname = location.hostname;
+    if (!hostname ||
+        hostname === 'localhost' ||
+        /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname)) {
+        return undefined;
+    }
+    const domain = psl.get(hostname);
+    return domain ? `.${domain}` : undefined;
+};
+const setCookie = (name, value) => {
+    Cookies.set(name, value, {
+        // 约 24 小时过期
+        expires: 1,
+        path: '/',
+        sameSite: 'Lax',
+        domain: getCookieDomain(),
+    });
+};
 /**
  * 获取设备 ID
- * @returns 设备 ID
- * - 如果设备 ID 不存在，则生成一个设备 ID 并返回
- * - 如果设备 ID 存在，则返回设备 ID
+ * 优先级：cookie > localStorage > 新生成
+ * - cookie 有值：返回并覆盖 localStorage
+ * - cookie 无、localStorage 有：返回并回写 cookie（含子域名可共享的 domain）
+ * - 都没有：生成新 ID，同时写入 cookie 与 localStorage
  */
 export const getDeviceId = () => {
-    const cacheKey = 'ftbzdid';
-    const deviceId = localStorageCache.get(cacheKey);
-    if (!deviceId) {
-        const uuid = getUuid();
-        localStorageCache.set(cacheKey, uuid);
-        return uuid;
+    const cookieDeviceId = Cookies.get(cookieName);
+    if (cookieDeviceId) {
+        localStorageCache.set(cacheKey, cookieDeviceId);
+        return cookieDeviceId;
+    }
+    const storageDeviceId = localStorageCache.get(cacheKey);
+    if (storageDeviceId) {
+        setCookie(cookieName, storageDeviceId);
+        return storageDeviceId;
     }
-    return deviceId;
+    const uuid = getUuid();
+    setCookie(cookieName, uuid);
+    localStorageCache.set(cacheKey, uuid);
+    return uuid;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatbiz/device",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "homepage": "https://gitlab.itcjf.com/flatjs/flat-biz-devkit",
   "repository": {
     "type": "git",
@@ -37,13 +37,17 @@
     "dev": "vite"
   },
   "dependencies": {
+    "js-cookie": "3.0.8",
+    "psl": "1.15.0",
     "ua-parser-js": "2.0.9"
   },
   "devDependencies": {
     "@hyperse/eslint-config-hyperse": "^1.7.3",
+    "@types/js-cookie": "3.0.6",
     "@types/node": "25.8.0",
     "eslint": "10.4.0",
     "happy-dom": "17.4.6",
+    "jsdom": "26.1.0",
     "npm-run-all": "4.1.5",
     "typescript": "6.0.3",
     "vite": "6.3.5",