用户来源与归因（转化）

在 SaaS 产品里，用户来源和归因是一项非常重要的基础设施，做用户分析、增长分析、投放分析都用得到。

从 v3.2.10 版本开始，NEXTY.DEV 新增了 userSource 表，内置了用户来源记录功能，支持通过环境变量 NEXT_PUBLIC_USER_SOURCE_TRACKING_ENABLED 设置是否开启。

功能亮点

NEXTY.DEV 是首个为开发者提供用户来源记录和归因功能的 SaaS 模板，让你产品开发之初即拥有如下功能：

• 一键开关：通过 NEXT_PUBLIC_USER_SOURCE_TRACKING_ENABLED 控制是否入库。
• 全面的来源数据：
  • 客户端捕获 UTM / referrer / landing page / 设备 / 语言等。
  • 服务端补全地理信息、解析浏览器信息。
• 隐私友好：如果你启用了 Cookie Consent（NEXT_PUBLIC_COOKIE_CONSENT_ENABLED），用户明确拒绝使用 Cookie，那么将不会写入 tracking cookie，保护用户隐私。
• 不侵入业务：来源逻辑与业务代码完全隔离，不会影响你原有的业务逻辑。
• 可扩展：user_source.metadata (jsonb) 预留了扩展空间，方便你未来接入自定义参数、广告平台 click id 等。

使用方式

1) 开启、关闭功能

通过环境变量 NEXT_PUBLIC_USER_SOURCE_TRACKING_ENABLED 设置开启关闭，true 为开启，false 为关闭，默认是 true

NEXT_PUBLIC_USER_SOURCE_TRACKING_ENABLED="true"

2) 启用 Cookie Consent（可选）

部分地区有严格的隐私合规要求，需要用户明确同意才能使用 Cookie，你可以通过环境变量 NEXT_PUBLIC_COOKIE_CONSENT_ENABLED 设置启用 Cookie Consent，true 为启用，false 为关闭，默认是 false。

NEXT_PUBLIC_COOKIE_CONSENT_ENABLED="true"

当你启用 Cookie Consent 后，用户在首次访问时会看到一个 Cookie 同意弹框，用户可以选择同意或拒绝。

当用户选择 Decline Cookies 时，客户端不会写入 user_tracking_data。

数据表说明：user_source

下面是这张表记录的核心字段：

• 渠道与分销（Affiliate）

  • aff_code：来自 URL 参数 aff / via / ref

• UTM 五件套

  • utm_source / utm_medium / utm_campaign / utm_term / utm_content

• 来源与落地页

  • referrer：完整 referrer URL
  • referrer_domain：从 referrer 解析出的 domain
  • landing_page：首次记录到的落地页 URL

• 设备与浏览器（User-Agent + 客户端补充）

  • user_agent
  • browser / browser_version
  • os / os_version
  • device_type
  • device_brand / device_model
  • screen_width / screen_height
  • language / timezone

• 网络与地理

  • ip_address
  • country_code

• 扩展

  • metadata (jsonb)：预留扩展字段（click id、自定义参数、实验分组等）

相关文件

以下是用户来源模块涉及的文件，如果需要二次开发，可选中让 AI 来完成自定义需求。

• lib/db/schema.ts：user_source 表结构
• lib/tracking/client.ts：客户端采集与写入 cookie
• lib/tracking/server.ts：服务端补全与写库
• lib/tracking/shared.ts：类型与公共方法
• lib/auth/index.ts：Better Auth hook 用户创建后写入 user_source
• actions/users/admin.ts：后台用户数据查询示例

在管理后台使用

模板用户管理功能已升级为联表查询，你可以在用户列表中看到用户来源数据。

你可以根据需求扩展添加数据：

• 在 Overview 页面展示用户来源数据图表或订单转化数据图表
• 在用户列表展示每个用户的订单数量或者历史付款金额

这个功能只需要简单修改几行查询语句即可实现，但因为并非每个产品都必须，所以模板没有内置。