# @fluid-app/fairshare 中文文档

规范地址：https://npmcn.com/package/%40fluid-app/fairshare/

版本：0\.2\.13
npm 元数据更新时间：2026-09-16T21:41:39.017Z
中文译文更新时间：2026-11-15T01:43:00.471Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fluid-app/fairshare
原文对照：https://npmcn.com/package/%40fluid-app/fairshare/?lang=original
项目主页：https://fluid.app/
源码仓库：https://github.com/fluid-app/fluid-npm

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：326 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-03-20T18:15:44.443Z
- 最新版本发布：2025-07-21T21:18:09.250Z
- 近 30 天下载量：21244（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 0 个）

## 中文简介

Fairshare 流体商务应用程序的功能

## 安装

```sh
npm install @fluid-app/fairshare
```

也可以使用：`pnpm add @fluid-app/fairshare`、`yarn add @fluid-app/fairshare`、`bun add @fluid-app/fairshare`

## README

# 公平分享 SDK

一个轻量级,以隐私为主的Fluid Commerce的SDK跟踪,可以无缝地跟踪用户事件,归属,以及转换,同时优先考虑性能和用户隐私.

## 重要: 与流体 SDK 整合

**对于大多数使用的案例,你不需要直接安装或初始化FairShare.**

FairShare在使用Fluid SDK时自动包含并初始化. 我们建议直接使用流体SDK进行最简单的整合:

```typescript
import { initializeFluid } from "@fluid-app/fluid";

// This initializes both Fluid SDK and FairShare
// Attribution is now handled server-side via the settings API
initializeFluid({
  fluidShop: "your-shop-id",
});
```

此文档的其余部分是用于高级使用的案例,您需要独立于流体SDK使用FairShare.

## 特征

-   **服务器侧归属**: 归属由流体商务后端通过设置 API 自动处理
-   **会话管理**: 使用本地 Storage 而不是 cookie 来维持会话
-   **页面访问跟踪**: 自动跟踪带有元数据的页面视图
-   **事件跟踪**: 便于使用用于跟踪自定义事件的API
-   **浏览器指纹**: 确定跨会归属的以隐私为重点的设备
-   **事件夹击**: 高效批量事件以尽量减少网络请求

## 安装

```bash
npm install @fluid-app/fairshare
# or
yarn add @fluid-app/fairshare
# or
pnpm add @fluid-app/fairshare
```

## 快速启动

```typescript
import { initializeFairshare, trackFairshareEvent } from "@fluid-app/fairshare";

// Initialize the SDK
initializeFairshare({
  fluidShop: "your-shop-id",
  debug: true, // Enable debug logging (optional)
  // Attribution is now handled server-side via the settings API
});

// Track a custom event (e.g., Add to Cart)
trackFairshareEvent({
  eventName: "ADD_TO_CART",
  data: {
    product_id: 123,
    variant_id: 456,
    quantity: 1,
  },
});
```

## 追踪

归属现在通过设置 API 由 Fluid Commerce 后端自动处理. 服务器剖析了URL并提供归属数据,从而消除了客户端模式匹配的需要.

### 服务器侧分配惠益

-   **自动 URL 解析**: 服务器自动从各种 URL 格式提取属性
-   **不需要客户端配置**: 归属模式由服务器端管理
-   **一致的归属**:集中逻辑确保所有接触点的归属一致
-   **业绩更好**: 不需要客户端正则ex处理

### 服务器侧归属如何工作

1.  当用户访问您的网站时, URL 会被发送到流体商务后端
2.  服务器使用集中归属逻辑解析 URL
3.  分配数据通过设置 API 返回并在当地存储
4.  所有跟踪事件自动包括服务器确定的归属
5.  根据服务器侧归属规则,转换额记入正确的来源

### 归属模式

公平分享使用 a **最后触摸归属模式** 默认。 这意味着,如果一个用户访问多个归属URL,最新的一个将被用于跟踪.

## API 参考

### 核心职能

#### `initializeFairshare(config)`

初始化了 FairShare SDK .

```typescript
interface FairshareConfig {
  // Required: Your Fluid shop identifier
  fluidShop: string;

  // Optional: Enable debug mode for console logging
  debug?: boolean;

  // Optional: Custom API endpoint for all Fluid API requests
  apiEndpoint?: string;

  // Optional: Attribution override that overrides URL-based attribution
  attributionOverride?:
    | {
        email: string;
      }
    | {
        username: string;
      }
    | {
        share_guid: string;
      }
    | {
        fluid_rep_id: number;
      }
    | {
        external_id: string;
      };

  // Optional: Configure tracking behavior
  trackingSettings?: {
    // Disable automatic page visit tracking on initialization (default: false)
    disableAutoPageTracking?: boolean;
  };

  // Optional: Configure event batching
  batchSize?: number; // Maximum events per batch (default: 10)
  batchInterval?: number; // Milliseconds between batch sends (default: 1000)
  maxQueueSize?: number; // Maximum events to store if offline (default: 100)
  flushIntervalMs?: number; // Auto-flush interval (default: 10000)
}
```

#### `trackFairshareEvent(event)`

跟踪带有数据的自定义事件.

```typescript
trackFairshareEvent({
  eventName: "CHECKOUT_STARTED",
  data: {
    cart_token: "cart_123456",
    metadata: {
      // Optional additional data
    },
  },
});
```

#### `getSessionToken()`

获取当前会话符号 .

```typescript
const sessionToken = getSessionToken();
```

#### `getAttribution()`

获取当前属性数据.

```typescript
const attribution = getAttribution();
console.log(attribution?.username); // e.g., "influencer-name"
console.log(attribution?.email); // e.g., "affiliate@example.com"
console.log(attribution?.share_guid); // e.g., "abc123-def456-ghi789"
console.log(attribution?.fluid_rep_id); // e.g., 12345
console.log(attribution?.external_id); // e.g., "external-affiliate-id"
```

#### `reset()`

清除所有存储的数据并重置 SDK 状态 .

```typescript
reset();
```

## 事件跟踪实例

### 添加到墨盒中

```typescript
trackFairshareEvent({
  eventName: "ADD_TO_CART",
  data: {
    product_id: 123,
    variant_id: 456,
    quantity: 1,
    price: "19.99",
    metadata: {
      // Optional additional data
      product_name: "Blue Sweater",
      category: "Apparel",
    },
  },
});
```

### 退出开始

```typescript
trackFairshareEvent({
  eventName: "CHECKOUT_STARTED",
  data: {
    cart_token: "cart_123456",
    metadata: {
      total_amount: "49.99",
      currency: "USD",
      items_count: 3,
    },
  },
});
```

## 调试

启用调试模式以查看浏览器控制台的详细记录 :

```typescript
initializeFairshare({
  fluidShop: "your-shop-id",
  debug: true,
  // Attribution is now handled server-side via the settings API
  // Optional: Use attribution override for specific scenarios
  // You can use any of these attribution data formats:
  attributionOverride: {
    email: "affiliate@example.com",
  },
  // OR
  // attributionOverride: { username: "influencer-username" },
  // OR
  // attributionOverride: { share_guid: "abc123-def456-ghi789" },
  // OR
  // attributionOverride: { fluid_rep_id: 12345 },
  // OR
  // attributionOverride: { external_id: "external-affiliate-id" },
});
```

您也可以直接检查本地Storage, 查看所存储的数据 :

-   `fs_attribution` - 当前归属数据
-   `fs_session` - 会话符号
-   `fs_fingerprint` - 浏览器指纹
-   `fs_event_queue` - 等待发送的排队活动

## 许可证

麻省理工学院

## 常见问题

### @fluid-app/fairshare 是什么？

Fairshare 流体商务应用程序的功能

### 如何安装 @fluid-app/fairshare？

在项目目录运行 npm install @fluid-app/fairshare，或使用 pnpm add / yarn add / bun add。

### @fluid-app/fairshare 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fluid-app/fairshare 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @fluid-app/fairshare 可以商用吗？

@fluid-app/fairshare 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fluid-app/fairshare 的下载量有多少？

根据 npm 官方下载统计，@fluid-app/fairshare 在 2026/10/15 – 2026/11/13 这 30 天内被下载 21,244 次，日均约 708 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fluid-app/fairshare 还在维护吗？

最新版本 0\.2\.13 发布于 2025/07/22（1\.3 年前）；至今共发布 30 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/03/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。