@ fluid-app/ fluid (英语)

官方JavaScript SDK为"流体通商",提供方便的车行管理,出站和归属追踪.

安装

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

快速启动

import {
  addCartItems,
  checkout,
  getCart,
  getCartItemCount,
  initializeFluid,
} from "@fluid-app/fluid";

// Initialize the SDK (typically in your app's entry point)
// Basic initialization with server-side attribution
initializeFluid({
  fluidShop: "your-shop-id", // Replace with your shop ID
});

// Optional: Initialize with attribution override
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    share_guid: "your-affiliate-id",
  },
});

// Examples of common operations:

// 1. Add a single item to cart
const cart1 = await addCartItems(12345);

// 2. Add a single item with quantity
const cart2 = await addCartItems(12345, { quantity: 3 });

// 3. Add multiple items to cart at once
const cart3 = await addCartItems([
  { variant_id: 12345, quantity: 1 },
  { variant_id: 67890, quantity: 2 },
]);

// 4. Get the current cart
const cart = await getCart();

// 5. Get the number of items in the cart
const itemCount = getCartItemCount();

// 6. Proceed to checkout (redirects user automatically)
await checkout();

快速引用

SDK 函数

初始化流体
获取卡特
获取Cart 项目
添加Cart 项目
更新Cart 项目
订阅Cart 项目
未订阅Cart 项目
减少Cart 项目
删除Cart 项目比德
清空卡尔特
获取本地卡
离职
重设
获取归属
查找关联
更新本地设置

部件

Cart 部件
控制墨盒
添加带有数据属性的产品
添加带有数据属性的滚动包
合并包装和产品
铅捕获部件

特征

墨盒管理: 创建推车、添加/移动项目并更新数量
退出流程: 自动重定向的一击取出
追踪: 内部跟踪附属营销
事件跟踪: 自动跟踪页面访问和推车互动
会话管理: 不带饼干处理用户会话
浏览器指纹: 跨部门用户识别
优化更新: 立即更新用户界面,以获得更好的用户体验
输入的 API: 具有准确类型的完整类型脚本支持

追踪

Fluid SDK默认包括了FairShare属性跟踪. 初始化时 initializeFluid(),属性跟踪自动设置 服务器侧属性计算。。。 .

服务器-系统分配如何工作

自动归属计算: 获取设置时, 属性现在是根据当前页面 URL 计算的服务器侧 .
页面更改检测:SDK自动检测URL变化(包括SPA导航)并视需要刷新归属数据.
归属覆盖支持: 您可以以特定值来覆盖基于 URL 的属性, 用于测试或固定的情景 .
归属优先制度: 归属比服务器计算归属优先.

基本服务器归属

// Basic initialization - attribution calculated server-side automatically
initializeFluid({
  fluidShop: "your-shop-id",
});

归属

// Attribution by email
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    email: "[email protected]",
  },
});

// Attribution by username
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    username: "influencer-username",
  },
});

// Attribution by share GUID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    share_guid: "abc123-def456-ghi789",
  },
});

// Attribution by Fluid rep ID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    fluid_rep_id: 12345,
  },
});

// Attribution by external ID
initializeFluid({
  fluidShop: "your-shop-id",
  attributionOverride: {
    external_id: "external-affiliate-id",
  },
});

API 参考

核心设置

初始化流体

initializeFluid(config)

初始化了Fluid SDK和集成的FairShare跟踪.

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

initializeFluid({
  fluidShop: "your-shop-id",
  debug: true, // Optional: enable debug logs
  apiEndpoint: "https://api.custom-endpoint.com", // Optional: custom API endpoint
});

您可以为本地开发、校验或连接到特定的 API 实例等情景提供自定义 API 端点 .

获取卡特

getCart()

从流体 API 获取当前手推车数据 .

import { getCart } from "@fluid-app/fluid";

// Get the latest cart data from the API
const cart = await getCart();

// Access cart properties
if (cart?.items?.length > 0) {
  console.log(
    `Cart has ${cart.items.length} items with a total of $${cart.total}`,
  );
}

这使得网络请求获取最新的推车信息. 使用本地缓存数据的快捷离线选项,请参见 getLocalCart()。。。 .

墨盒管理

获取Cart 项目

获得车内当前项目的数量.

import { getCartItemCount } from "@fluid-app/fluid";

// Get the current cart item count
const itemCount = getCartItemCount();
console.log(`Cart contains ${itemCount} items`);

添加Cart 项目

在推车中添加物品,如果已经装入车内,则增加其数量.

// Add/increment a single item by 1
const cart1 = await addCartItems(12345);

// Add/increment a single item by 3
const cart2 = await addCartItems(12345, { quantity: 3 });

// Add/increment multiple items at once
const cart3 = await addCartItems([
  { variant_id: 12345, quantity: 2 },
  { variant_id: 67890, quantity: 1 },
]);

// Add an item with subscription
const cart4 = await addCartItems(12345, { subscribe: true });

// Add multiple items with mixed subscription preferences
const cart5 = await addCartItems([
  { variant_id: 12345, quantity: 1, subscribe: true },
  { variant_id: 67890, quantity: 2 },
]);

更新Cart 项目

立即更新多件手推车物品的数量,对物品数量进行精确控制.

import { updateCartItems } from "@fluid-app/fluid";

// Set exact quantities for multiple items
const cart = await updateCartItems([
  { variant_id: 12345, quantity: 3 },
  { variant_id: 67890, quantity: 1 },
]);

// This will set the quantities exactly as specified, regardless of previous values

订阅Cart 项目

设置要作为订阅购买的手推车项目 .

// Convert an existing cart item to a subscription
await subscribeCartItem(123); // where 123 is the item ID (not variant ID)

未订阅Cart 项目

将一个手推车项目从订阅改为一次性购买.

// Convert a subscription cart item back to a one-time purchase
await unsubscribeCartItem(123); // where 123 is the item ID (not variant ID)

减少Cart 项目

将车内物品的数量减少规定数量(如果没有规定数量,则减少1个)。如果数量为0,则从车中取出物品.

// Decrement item by 1 (removes if quantity becomes 0)
const cart1 = await decrementCartItem(12345);

// Decrement item by 2
const cart2 = await decrementCartItem(12345, { quantity: 2 });

删除Cart 项目比德

以项目 ID (而不是变体 ID) 完全删除一个手推车项目。此功能可用于删除全部项目而不论数量, 如入学包 .

import { removeCartItemById } from "@fluid-app/fluid";

// Remove a cart item completely using its item ID
const cart = await removeCartItemById(itemId);

// This is particularly useful for enrollment packs
// where you want to remove the entire pack
const enrollmentItem = cart.items.find((item) => item.enrollment_pack_id);
if (enrollmentItem) {
  await removeCartItemById(enrollmentItem.id);
}

清空卡尔特

删除手推车中的所有项目并删除手推车会话.

clearCart();

获取本地卡

直接从本地存储中获取当前推车, 而无需 API 调用 .

const cart = getLocalCart();
if (cart?.items?.length > 0) {
  console.log(`Cart has ${cart.items.length} items`);
}

在 HTML 中显示墨盒计数

您可以在 HTML 元素中轻松显示当前手推车的计数, 方法是给它ID fluid-cart-count。SDK会自动更新此元素, 当拖车改变时.

<!-- Simple cart count display -->
<span id="fluid-cart-count">0</span>

当 :

东西被加进车里
东西从车上搬走
项目数量得到更新
车已经清空了
创建一个新的推车
车是从API刷新出来的

离职

启动退出程序。这个:

等待任何待办的推车操作完成
如果有归属数据,则包括归属数据
重定向到流体取出页面

try {
  await checkout();
  // User is redirected automatically
} catch (error) {
  console.error("Checkout failed:", error);
}

公用事业

重设

重置整个SDK状态,包括清除车和所有跟踪数据.

import { reset } from "@fluid-app/fluid";

// Clear all data and reset state
reset();

获取归属

获取当前属性数据.

import { getAttribution } from "@fluid-app/fluid";

const attribution = getAttribution();
if (attribution?.username) {
  console.log("Referred by username:", attribution.username);
} else if (attribution?.email) {
  console.log("Referred by email:", attribution.email);
} else if (attribution?.share_guid) {
  console.log("Referred by share GUID:", attribution.share_guid);
} else if (attribution?.fluid_rep_id) {
  console.log("Referred by Fluid rep ID:", attribution.fluid_rep_id);
} else if (attribution?.external_id) {
  console.log("Referred by external ID:", attribution.external_id);
}

查找关联

通过归属数据查找关联信息.

import { lookupAffiliate } from "@fluid-app/fluid";

// Look up affiliate by username
try {
  const result = await lookupAffiliate({ username: "affiliate-username" });

  if (result?.affiliate) {
    console.log("Affiliate found:", result.affiliate.name);
    console.log("Email:", result.affiliate.email);
    console.log("Username:", result.affiliate.username);
    console.log("Share GUID:", result.affiliate.share_guid);
  }
} catch (error) {
  console.error("Affiliate not found or lookup failed:", error);
}

// Other lookup methods:
await lookupAffiliate({ email: "[email protected]" });
await lookupAffiliate({ share_guid: "abc123" });
await lookupAffiliate({ fluid_rep_id: 123456 });
await lookupAffiliate({ external_id: "EXT-789" });

该函数可用于验证附属标识符或检索附属信息以用于显示目的.

更新本地设置

更新手推车的语言和国别等地方设置.

import { updateLocaleSettings } from "@fluid-app/fluid";

// Update language only
await updateLocaleSettings({ language: "fr" });

// Update country only
await updateLocaleSettings({ country: "CA" });

// Update both language and country
await updateLocaleSettings({
  language: "fr",
  country: "CA",
});

这对多语言/多区域商店很有用,以确保推车使用适当的地盘设置.

Web 部件

Fluid提供随时可以使用的网络组件,很容易被整合到任何网站. 这些部件提供了精简的购物体验,不需要复杂的自定义执行.

安装

这些部件可通过CDN或作为国家防范机制软件包使用.

CDN / 脚本标签分发

使用这种方法直接纳入一个没有构建步骤的网站.

<!-- Fluid SDK script tag with configuration attributes -->
<script
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
  data-fluid-shop="your-shop-id"
  data-fluid-api-base-url="https://api.your-custom-endpoint.com"
></script>
<!-- ^ The data-fluid-api-base-url attribute specifies a custom API endpoint -->
<!-- Attribution is now handled automatically server-side based on the page URL -->

<!-- Add the cart widget anywhere on your page -->
<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store Name"
></fluid-cart-widget>

CDN分发的主要好处

无需安装国家预防机制 - 任何HTML页面的工作
自动样式插入 - 没有单独的CSS文件可以包含
单脚本标签处理所有事务 - 初始化SDK、加载样式、登记组件
通过数据属性的灵活性数字 :
- data-fluid-shop - 您的店牌( 需要)
- data-fluid-api-base-url - 使用自定义的API端点(用于开发/安装)
- data-share-guid - 设置硬码归属(可选)
- data-debug - 启用调试模式

装置

npm install @fluid-app/web-widgets

// Import the components and styles
import { initializeFluid } from "@fluid-app/fluid";
import { registerWebComponents } from "@fluid-app/web-widgets";

import "@fluid-app/web-widgets/styles.css";

// Initialize Fluid SDK with your shop ID
initializeFluid({
  fluidShop: "your-shop-id",
});

// Register the web components
registerWebComponents();

可用的部件

推车部件为您的网站提供了浮动推车按钮和抽屉接口 .

<!-- Basic cart widget -->
<fluid-cart-widget
  position="bottom-right"
  fluid-shop-display-name="Your Store"
></fluid-cart-widget>

属性 :

属性	类型	默认	说明
职位	字符串	"从下到上"	屏幕上的位置 : “ 左上” 、 “ 右上” 、 “ 左下” 、 “ 右下”
流体处理- 播放- 名称	字符串	"我的仓库"	在车头显示店名
大小	编号	页:1	元件按像素键的大小
x-边距	编号	第40条	从边缘到像素水平边距
y-边距	编号	98国	从像素边缘起的垂直边距
z 指数	编号	第50条	用于分层的 Z 索引
隐藏窗口	布尔	虚假	真实时, 隐藏按钮但保留拖车功能

控制墨盒

您可以使用数据属性控制推车 :

<!-- Cart control buttons -->
<button data-fluid-cart="open">Open Cart</button>
<button data-fluid-cart="close">Close Cart</button>
<button data-fluid-cart="toggle">Toggle Cart</button>

或使用 Java 脚本 :

// When using NPM package
import { closeCart, openCart, toggleCart } from "@fluid-app/react-widgets";

openCart();
closeCart();
toggleCart();

// When using CDN
window.fluidCart.open();
window.fluidCart.close();
window.fluidCart.toggle();

添加带有数据属性的产品

数据属性提供了一个简单的方法,无需写入 JavaScript 即可将产品添加到拖车中 :

<!-- Basic usage with default quantity (1) - cart opens automatically -->
<button data-fluid-add-to-cart="22190">Add to Cart</button>

<!-- With specific quantity - cart opens automatically -->
<button data-fluid-add-to-cart="22190" data-fluid-quantity="2">
  Add 2 to Cart
</button>

<!-- Add to cart without opening cart drawer immediately -->
<button data-fluid-add-to-cart="22190" data-fluid-open-cart-after-add="false">
  Add to Cart (Keep Shopping)
</button>

<!-- Add with subscription enabled -->
<button data-fluid-add-to-cart="22190" data-fluid-subscribe="true">
  Add with Subscription
</button>

<!-- Add multiple products with one subscribed -->
<button data-fluid-add-to-cart="22190,22191" data-fluid-subscribe="true,false">
  Add Multiple (First Subscribed)
</button>

添加带有数据属性的滚动包

使用数据属性可以添加输入包 :

<!-- Basic usage to add an enrollment pack - cart opens automatically -->
<button data-fluid-add-enrollment-pack="64">Add Enrollment Pack</button>

<!-- Add enrollment pack without opening cart drawer immediately -->
<button
  data-fluid-add-enrollment-pack="64"
  data-fluid-open-cart-after-add="false"
>
  Add Enrollment Pack (Keep Shopping)
</button>

合并包装和产品

您可以将招生包和普通产品合并为一个单项行动:

<!-- Add enrollment pack and product together -->
<button data-fluid-add-enrollment-pack="64" data-fluid-add-to-cart="22190">
  Add Enrollment Pack with Product
</button>

<!-- Add multiple products with the enrollment pack -->
<button
  data-fluid-add-enrollment-pack="64"
  data-fluid-add-to-cart="22190,22191"
>
  Add Enrollment Pack with Multiple Products
</button>

<!-- With subscription enabled for the products -->
<button
  data-fluid-add-enrollment-pack="64"
  data-fluid-add-to-cart="22190,22191"
  data-fluid-subscribe="true"
>
  Add Pack with Subscribed Products
</button>

<!-- Different subscription settings for each product -->
<button
  data-fluid-add-enrollment-pack="64"
  data-fluid-add-to-cart="22190,22191"
  data-fluid-subscribe="true,false"
>
  Add Pack with Mixed Subscription Products
</button>

主抓取部件提供了收集客户信息的表格.

<!-- Basic lead capture widget -->
<fluid-lead-capture-widget
  title="Get Updates"
  contact-method="phone"
></fluid-lead-capture-widget>

您可以使用 CSS 变量自定义部件以匹配您的品牌 :

:root {
  --company-color: #4361ee; /* Your brand color */
  --ff-body: "Your Custom Font", sans-serif; /* Your custom font */
}

--company-color: 设置按钮、口音和亮点的主要颜色
--ff-body: 设置整个部件所用的字体家族( 如果未指定则返回系统字体)

这使得您可以在您的网站和流体部件上保持一致的品牌和打字功能.

调试

启用调试模式以查看详细日志 :

initializeFluid({
  fluidShop: "your-shop-id",
  debug: true,
});

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

fs_cart: 文件数据
fs_attribution: 归属数据
fs_session: 会话符号

许可证

麻省理工学院

版本	发布日期	距今
`1.1.5`latest	2025/07/22	1.3 年前
`1.1.4`	2025/07/18	1.3 年前
`1.1.3`	2025/07/18	1.3 年前
`1.1.2`	2025/07/16	1.3 年前
`1.1.1`	2025/07/16	1.3 年前
`1.1.0`	2025/07/16	1.3 年前

@fluid-app/fluid