归因脚本

归因脚本用于收集访客上下文信息（UTM 参数、来源页、设备信息），并存储在 Cookie 中。当客户结账时，你将这些数据作为结账 metadata 传递，Money Fast 就能将每笔订单归因到对应的流量来源。

第一步：安装脚本

在你网站的 <head> 中添加以下脚本标签：

<script defer data-website-id="YOUR_SITE_ID" src="https://moneyfa.st/js/script.min.js"></script>

将 YOUR_SITE_ID 替换为你的实际 Site ID，可以在 Money Fast 仪表盘的网站设置页面找到。

脚本非常轻量（gzip 后约 1KB），异步加载，会设置一个名为 _moneyfast 的 Cookie 来存储归因数据。Cookie 有效期 30 天，当访客携带新的 UTM 参数访问时会自动刷新。

调试模式

想查看脚本收集了什么数据，可以启用调试模式：

<script defer data-website-id="YOUR_SITE_ID" data-debug="true" src="https://moneyfa.st/js/script.min.js"></script>

打开浏览器开发者控制台，可以看到 [MoneyFast] 开头的日志信息。

第二步：在结账时传递 Metadata

创建结账会话时，读取 Cookie 并将其值作为 metadata 传递。以下以 Stripe 为例，其他支付平台类似。

Stripe — Node.js / Next.js 示例

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

// 从请求头解析 _moneyfast cookie
function getMoneyFastMeta(cookieHeader) {
  const match = cookieHeader?.match(/(^| )_moneyfast=([^;]+)/);
  if (!match) return {};
  try {
    return JSON.parse(decodeURIComponent(match[2]));
  } catch {
    return {};
  }
}

// 创建 Checkout Session
export async function createCheckout(req) {
  const meta = getMoneyFastMeta(req.headers.get('cookie'));
  // 添加 exit_page，移除内部字段
  meta.moneyfast_exit_page = new URL(req.url).pathname;
  delete meta.moneyfast_ts;

  const session = await stripe.checkout.sessions.create({
    mode: 'subscription', // 或 'payment'
    line_items: [{ price: 'price_xxx', quantity: 1 }],
    success_url: 'https://example.com/success',
    cancel_url: 'https://example.com/cancel',
    // 传递 metadata 到 checkout session
    metadata: meta,
    // 订阅类产品还需要传到 subscription_data
    subscription_data: {
      metadata: meta,
    },
  });

  return session.url;
}

客户端（浏览器）示例

如果你从前端创建结账会话，可以使用全局的 MoneyFast.meta() 方法：

const response = await fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    priceId: 'price_xxx',
    // 传递 MoneyFast 归因 metadata
    metadata: window.MoneyFast?.meta() || {},
  }),
});

然后在服务端，将 metadata 合并到结账会话中：

const session = await stripe.checkout.sessions.create({
  // ...其他选项
  metadata: req.body.metadata,
  subscription_data: {
    metadata: req.body.metadata,
  },
});

Metadata 字段说明

所有字段使用 moneyfast_ 前缀。Money Fast 会自动从支付事件的 metadata 中读取这些数据。

字段	说明	来源
`moneyfast_ref`	流量来源	`utm_source`、`ref` 或 `via` 查询参数
`moneyfast_campaign`	营销活动	`utm_campaign` 查询参数
`moneyfast_medium`	流量媒介	`utm_medium` 查询参数
`moneyfast_term`	搜索关键词	`utm_term` 查询参数
`moneyfast_content`	广告内容	`utm_content` 查询参数
`moneyfast_landing_page`	着陆页	自动检测
`moneyfast_exit_page`	结账页面	由 `MoneyFast.meta()` 设置
`moneyfast_referrer`	来源 URL	自动检测
`moneyfast_device`	设备类型	`desktop`、`mobile` 或 `tablet`
`moneyfast_browser`	浏览器	自动检测
`moneyfast_os`	操作系统	自动检测
`moneyfast_lang`	浏览器语言	自动检测
`moneyfast_tz`	时区	自动检测

JavaScript API

脚本暴露了一个全局的 MoneyFast 对象：

// 获取 Cookie 中的原始归因数据
MoneyFast.get()

// 获取用于结账的 metadata（添加 exit_page，移除内部字段）
MoneyFast.meta()

// 手动重新收集归因数据
MoneyFast.collect()

// 清除归因 Cookie
MoneyFast.clear()

注意事项

订阅 metadata（Stripe）：Stripe 不会自动将结账会话的 metadata 传递到订阅对象。你必须显式设置 subscription_data.metadata，否则续费事件将缺失归因数据。
Cookie 作用域：_moneyfast Cookie 设置在你的域名下，使用 SameSite=Lax。它在你网站的所有页面上有效，但不会跨域追踪。
无 PII：脚本不收集任何个人身份信息，只捕获 UTM 参数、页面 URL 和设备/浏览器信息。

AI Agent 集成 Prompt

复制以下 prompt，粘贴给你的 AI 编码助手（Cursor、Claude Code、Windsurf 等），即可正确集成 Money Fast 归因追踪。

将 Money Fast (moneyfa.st) 收入归因追踪集成到本项目中。请严格按照以下指令操作。

## 1. 安装追踪脚本

**方式 A：npm 包（推荐 Next.js / React 项目）**

```bash
npm i analytics-script
```

```tsx
// app/layout.tsx（或 _app.tsx 等）
import { MoneyFast } from 'analytics-script';

// 在 <head> 中添加 <MoneyFast websiteId="YOUR_SITE_ID" />
```

**方式 B：Script 标签（任意网站）**

在网站的 `<head>` 中添加脚本标签（根 layout、_app、index.html 等）：

```html
<script defer data-website-id="YOUR_SITE_ID" src="https://moneyfa.st/js/script.min.js"></script>
```

将 `YOUR_SITE_ID` 替换为 Money Fast 仪表盘设置页面中的 Site ID。

## 2. 将归因数据传递到 Stripe Checkout metadata

找到创建 Stripe Checkout Session 的代码，添加 MoneyFast 归因 metadata。

### 如何读取 Cookie

**如果使用 npm 包**，可以直接用辅助函数：

```js
import { getMoneyFastMeta } from 'analytics-script';
const meta = getMoneyFastMeta(); // 客户端调用，返回可直接传给 Stripe 的 metadata
```

**如果使用 script 标签**，脚本会设置一个 `_moneyfast` Cookie，读取方式：

```js
JSON.parse(decodeURIComponent(cookieValue))
```

### ⚠️ 关键：不要添加 `moneyfast_` 前缀

Cookie 中的 key 已经包含 `moneyfast_` 前缀。Cookie 内容如下：

```json
{ "moneyfast_ref": "google", "moneyfast_device": "desktop", "moneyfast_browser": "Chrome", "moneyfast_os": "Windows", "moneyfast_landing_page": "/", "moneyfast_ts": 1710000000 }
```

直接使用这些 key。如果你再加一层 `moneyfast_` 前缀，key 会变成 `moneyfast_moneyfast_device`，所有归因数据将会丢失。

```js
// ❌ 错误
meta[`moneyfast_${key}`] = value;

// ✅ 正确
meta[key] = value;
```

### 需要过滤的内容

- 排除 `moneyfast_ts`（内部时间戳，metadata 不需要）
- 添加 `moneyfast_exit_page` = 结账时的当前页面路径（从客户端通过 `window.location.pathname` 获取）
- 只包含 Cookie 中的 string 类型值

### metadata 传递位置

根据结账模式，将 metadata 传递到以下所有位置：

- `metadata` — 必须（checkout session 本身）
- `subscription_data.metadata` — 如果 mode 为 `subscription`（Stripe 不会自动将 session metadata 传播到订阅对象）
- `payment_intent_data.metadata` — 如果 mode 为 `payment` 且启用了 `invoice_creation`

## 3. 自定义事件（可选）

脚本还支持追踪前端自定义事件：

```js
MoneyFast.track('signup_click')
MoneyFast.track('pricing_view')
```

事件名称：仅支持字母、数字、下划线、连字符和点号（最长 100 字符）。需要在 script 标签上设置 `data-website-id`。

## 4. 验证

实现完成后验证：
1. 访问网站，打开 DevTools 控制台，运行 `MoneyFast.get()` — 应返回包含归因数据的对象
2. 创建一个测试 checkout，在 Stripe Dashboard → Checkout Session → Metadata 中检查 — key 应该是 `moneyfast_device`、`moneyfast_browser` 等（单层前缀，不是 `moneyfast_moneyfast_*`）

归因脚本

本页目录