公平分享 SDK
一个轻量级,以隐私为主的Fluid Commerce的SDK跟踪,可以无缝地跟踪用户事件,归属,以及转换,同时优先考虑性能和用户隐私.
重要: 与流体 SDK 整合
对于大多数使用的案例,你不需要直接安装或初始化FairShare.
FairShare在使用Fluid SDK时自动包含并初始化. 我们建议直接使用流体SDK进行最简单的整合:
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
- 浏览器指纹: 确定跨会归属的以隐私为重点的设备
- 事件夹击: 高效批量事件以尽量减少网络请求
安装
npm install @fluid-app/fairshare
# or
yarn add @fluid-app/fairshare
# or
pnpm add @fluid-app/fairshare
快速启动
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处理
服务器侧归属如何工作
- 当用户访问您的网站时, URL 会被发送到流体商务后端
- 服务器使用集中归属逻辑解析 URL
- 分配数据通过设置 API 返回并在当地存储
- 所有跟踪事件自动包括服务器确定的归属
- 根据服务器侧归属规则,转换额记入正确的来源
归属模式
公平分享使用 a 最后触摸归属模式 默认。 这意味着,如果一个用户访问多个归属URL,最新的一个将被用于跟踪.
API 参考
核心职能
initializeFairshare(config)
初始化了 FairShare SDK .
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)
跟踪带有数据的自定义事件.
trackFairshareEvent({
eventName: "CHECKOUT_STARTED",
data: {
cart_token: "cart_123456",
metadata: {
// Optional additional data
},
},
});
getSessionToken()
获取当前会话符号 .
const sessionToken = getSessionToken();
getAttribution()
获取当前属性数据.
const attribution = getAttribution();
console.log(attribution?.username); // e.g., "influencer-name"
console.log(attribution?.email); // e.g., "[email protected]"
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 状态 .
reset();
事件跟踪实例
添加到墨盒中
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",
},
},
});
退出开始
trackFairshareEvent({
eventName: "CHECKOUT_STARTED",
data: {
cart_token: "cart_123456",
metadata: {
total_amount: "49.99",
currency: "USD",
items_count: 3,
},
},
});
调试
启用调试模式以查看浏览器控制台的详细记录 :
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: "[email protected]",
},
// 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- 等待发送的排队活动
许可证
麻省理工学院