归因分析
TanStack Ship 归因分析仪表板，支持多渠道转化追踪、基于 UTM 的活动 ROI 衡量和趋势分析。
概述
TanStack Ship 的归因分析仪表板为您的营销渠道如何驱动转化和收入提供了全面的可见性。通过将用户旅程追溯回其原始 UTM 参数——来源、媒介、活动和内容——系统揭示了哪些活动、流量来源和营销渠道能带来最高的投资回报率。
作为 TanStack Ship 平台的一部分，归因分析系统处理来自 UTM 追踪模块（在注册时捕获用户触点）、账单系统（追踪哪些订阅转化）和短链接模块（衡量点击归因）的数据。这种统一视图支持跨所有获客渠道的数据驱动营销决策。
归因数据管道
归因系统通过结构化数据管道将每次转化追溯回其营销来源：
设计理念
归因分析系统基于三个核心原则构建：
- 数据驱动决策 — 每个营销 KPI（归因转化数、收入、CPA、转化率）都被量化并可视化。决策基于可衡量的结果而非直觉，实现跨渠道的客观预算分配。
- 末次接触与首次接触双重上下文 — 默认的末次接触归因模型将全部信用归于转化前最近的 UTM 参数。同时首次接触数据也被保留，提供原始获客渠道的上下文参考。
- 透明衡量 — 所有归因逻辑具有确定性和可审计性。每次转化都可以追溯回其来源参数，实现精确的 ROI 计算，消除黑盒营销分析。与 Triple Whale 或 Mixpanel 不同——它们依赖概率归因模型和第三方数据增强——我们的系统基于在每个接触点捕获的实际 UTM 参数，使用确定性的第一方归因，确保每个指标完全可审计。
核心能力
归因仪表板
位于 /dashboard/admin/attribution-dashboard 的主分析仪表板提供了营销效果的综合视图：
- KPI 卡片 — 关键绩效指标一目了然，包括总归因转化数、归因收入、平均转化率和单次获客成本（CPA）
- 趋势图表 — 折线图显示可配置时间段内的归因趋势，支持日、周或月聚合
- 来源分解 — 按 UTM 来源（google、twitter、linkedin、facebook、直接、邮件）的流量和转化分布
- 活动排名 — 按转化数、总归因收入和 ROI 百分比排名的最佳活动
- 详细数据表格 — 粒度归因数据，支持多列筛选、可排序列和 CSV 导出功能
编程式分析访问示例：
import { useQuery } from '@tanstack/react-query'
function AttributionMetrics() {
const { data } = useQuery({
queryKey: ['attribution-summary'],
queryFn: () =>
fetch('/api/attributions/summary').then((r) => r.json()) as Promise<{
attributedConversions: number
attributedRevenue: number
avgConversionRate: number
cpa: number
}>,
})
return (
<div className="rounded-lg border p-4">
<h3 className="mb-3 font-semibold">归因 KPI</h3>
<dl className="grid grid-cols-2 gap-4">
<div>
<dt className="text-sm text-muted-foreground">转化数</dt>
<dd className="text-xl font-bold">{data?.attributedConversions.toLocaleString() ?? '—'}</dd>
</div>
<div>
<dt className="text-sm text-muted-foreground">收入</dt>
<dd className="text-xl font-bold">¥{data?.attributedRevenue.toLocaleString() ?? '—'}</dd>
</div>
<div>
<dt className="text-sm text-muted-foreground">转化率</dt>
<dd className="text-xl font-bold">{data?.avgConversionRate != null ? `${data.avgConversionRate}%` : '—'}</dd>
</div>
<div>
<dt className="text-sm text-muted-foreground">CPA</dt>
<dd className="text-xl font-bold">¥{data?.cpa.toFixed(2) ?? '—'}</dd>
</div>
</dl>
</div>
)
}
多来源归因报告
归因数据可跨多个维度进行切片分析：
- UTM 来源 — 识别哪些流量来源（搜索引擎、社交媒体平台、引荐网站）产生最有价值的转化
- UTM 媒介 — 比较不同流量类型的效果，如 CPC（付费搜索）、社交（自然社交）、邮件和引荐
- UTM 活动 — 评估单个活动表现，以将预算分配到表现最佳的方案
- UTM 内容 — 分析特定广告变体或链接变体，在细粒度层面优化创意元素
- 交叉分析 — 组合维度获取更深入洞察，如来源 × 活动或媒介 × 内容的转化表现
用户全生命周期转化追踪
系统在用户旅程的每个阶段追踪归因转化：
- 用户注册 — 新用户注册归因于注册时的 UTM 参数
- 订阅购买 — 用户订阅付费计划时，转化计入获客来源
- 积分购买 — 积分购买作为转化事件追踪，附带完整归因详情
- 可配置事件 — 可定义额外转化事件以追踪特定业务指标
每个转化事件记录完整的归因链——原始 UTM 参数、用户 ID、转化类型、货币价值和时间戳——实现按营销渠道的精确 ROI 计算。
趋势分析与效果比较
通过可视化归因指标随时间的变化来识别趋势和季节性：
- 期比期比较 — 比较两个日期范围之间的归因指标以衡量增长或下降
- 群组分析 — 按获客期间分组转化，分析按营销渠道的长期价值
- 季节性趋势检测 — 识别与季节性事件、活动和节假日相关的渠道表现的重复模式
- 自定义日期范围 — 灵活的日期筛选，带有常用期间的预设（最近 7 天、本月、上月、季度至今、年初至今）
最佳实践
一致的 UTM 命名约定
在所有营销活动中建立并执行一致的 UTM 命名约定。标准化来源名称（使用 google而非 Google 或 google.com）、媒介分类（cpc、social、email、referral）和活动命名模式（{渠道}-{活动}-{日期}）。一致性确保归因数据在仪表板中正确聚合，不会出现碎片化的维度值。
注意末次接触归因
系统默认使用末次接触归因模型，即转化前最近的 UTM 参数获得全部归因信用。请注意，该模型可能高估漏斗底部的渠道价值，低估品牌知名度工作。为获得更完整的视图，建议将归因数据与活动和优惠系统交叉引用，以了解辅助转化。
活动参数规范性
始终在活动 URL 中包含完整的 UTM 参数。缺少 utm_source 和 utm_medium 的活动将被归类为"直接/无"，并被排除在有意义的归因报告之外。使用活动管理系统的 UTM 构建器，确保所有营销链接的参数集完整且一致。
定期效果评审
安排定期的归因评审周期——活跃活动每周一次，战略规划每月一次。使用期比期比较功能识别积极趋势（成功的渠道优化）和负面变化（渠道效果下降或市场变化）。
常见问题
系统如何捕获 UTM 参数？
UTM 参数通过客户端脚本 src/lib/utm.ts 在每个页面加载时从 URL 查询字符串中捕获。参数在浏览器 cookie 中持久化，默认过期时间为 30 天，并在注册时保存到用户的数据库记录。
系统使用什么归因模型？ 系统默认使用末次接触归因模型。转化事件前捕获的最新的 UTM 参数获得该转化的全部归因信用。可通过归因服务配置实现自定义归因模型。
能否追踪订阅和注册以外的转化？ 可以。系统支持可配置的转化事件。您可以在归因配置中定义额外的转化类型，以追踪特定业务指标，如功能采用、演示请求或内容下载。
归因数据保留多久？ 归因数据在数据库中无限期保留。仪表板支持任意日期范围选择，允许您分析历史趋势、比较同比效果并识别渠道效果的长期变化。
系统如何处理直接流量和未标记的访问？ 没有 UTM 参数的访问被归类为"直接/无"并单独追踪。这些访问在仪表板中显示为未分配流量，不归因于任何营销渠道，帮助您区分自然增长和活动驱动增长。
能否导出归因数据用于外部分析？ 可以。仪表板包含 CSV 导出功能，可下载筛选后的归因数据，用于电子表格应用或 BI 工具中的外部分析。
单次获客成本（CPA）如何计算？ CPA 基于可配置的成本数据计算，可按活动导入。系统将总活动支出除以归因转化数，生成渠道级别和活动级别的 CPA 指标。
配置
归因分析仪表板访问地址为 /dashboard/admin/attribution-dashboard，需要：
- 激活的 UTM 追踪（默认包含在根布局中）
- 用户注册和带 UTM 归因记录的转化事件
- 管理角色对仪表板的访问权限
核心归因功能无需额外环境变量。对于成本数据导入，归因服务支持活动成本配置端点 /api/attributions/costs。
集成点
归因分析系统与以下 TanStack Ship 平台模块集成：