datafast

适用场景

• 你需要为网站（静态网站、SPA、Next.js、Astro 等）接入 DataFast 跟踪。
• 你需要将收入归因到营销渠道（Stripe、LemonSqueezy、Polar、自定义服务商）。
• 你希望可靠地记录自定义事件／目标，即使有广告拦截器也不受影响。
• 你必须代理跟踪器／脚本，以提高数据质量或启用哈希导航。
• 你希望导出／导入历史分析数据，或查询 DataFast API。

快速入门（4 步）

1. 在 <head> 中安装跟踪脚本：

   <script
     defer
     data-website-id="dfid_XXXX"
     data-domain="example.com"
     src="https://datafa.st/js/script.js"
   ></script>
   

   • 可通过 data-allow-localhost、data-api-url、data-debug、data-allowed-hostnames、data-disable-console、data-allow-file-protocol 进行自定义。
   • 添加 datafast-queue 代码片段，以便在库加载前将调用加入队列。
2. 连接支付服务商（Stripe、LemonSqueezy、Polar、Shopify 等）：在 Revenue 标签页中连接，即可让 DataFast 自动跟踪收入。
3. 添加自定义目标／事件：使用 window.datafast("my_goal")、data-fast-goal 属性或服务端 Goals API。
4. 可选：设置代理，以绕过广告拦截器：将 /js/script.js 和 /api/events 重写到你的域名，并通过 x-datafast-real-ip 转发访客 IP。

安装参考

• 在各类框架（Next.js App Router、React、Vue、Astro 等）中，通过 <Script /> 组件加载脚本，或在 public/index.html 中以声明方式添加。
• 对于基于哈希的导航，请使用支持哈希的脚本 https://datafa.st/js/script.hash.js。
• 使用 GTM、Shopify、Webflow、Wix、Podia、Kajabi、Ghost、Bubble、Framer、Astro、React Router、Laravel、Django、FastAPI、Flask、Express、PHP、Nginx、Firebase、Rocket 等平台时，将同一脚本添加到 <head> 或平台专用的 head／自定义代码区域即可。

收入归因最佳实践

• 跟踪脚本上线后，前往 Website Settings → Revenue 并添加每个支付服务商。
• 创建结账会话时，始终传递 datafast_visitor_id（也可传递 datafast_session_id）：
  • Stripe Checkout / PaymentIntent：从 cookies() 或 request.cookies 读取 Cookie，并将其添加到 metadata。
  • LemonSqueezy：将 DataFast Cookie 放入 custom。
  • Polar：将 Cookie 添加到 metadata。
  • Paddle / Dodo Payments / Easytool / Custom：调用 Payments API，或使用客户邮箱触发 payment 目标。
• 对于 DataFast 已会拉取收入的支付网关（Shopify、Stripe、LemonSqueezy、Polar），保留已安装的跟踪代码片段，但不要重复发送手动事件。
• 记录元数据映射，并确保下游任务会为每个财务事件读取 datafast_visitor_id。

自定义事件与目标

方法 1 – window.datafast()（客户端）

• 在点击、成功页面或 API 响应后触发 window?.datafast("goal_name")。
• 记录参数：window.datafast("checkout", { price: "49", plan: "pro" })。

方法 2 – HTML data 属性

• 为按钮／链接添加 data-fast-goal="goal_name"。
• 使用 data-fast-goal-* 属性补充信息（data-fast-goal-price="49" 会变为 { price: "49" }）。

方法 3 – 服务端 Goals API

• 向 https://datafa.st/api/v1/goals 发送 POST 请求，包含 datafast_visitor_id、name 和可选的 metadata。
• 使用 Authorization: Bearer YOUR_API_KEY 进行身份验证。
• 确保该访客至少产生过一次页面浏览（通过脚本跟踪）。

漏斗、滚动与筛选器

• 在关键版块（功能、定价、用户评价）上使用 data-fast-scroll，当元素有 50% 可见时发送滚动目标。
• 将滚动目标与漏斗（访问落地页 → 滚动查看功能 → 点击 CTA）结合，以发现流失环节。
• 跟踪 DataFast 自动跟踪的 UTM/ref/via 参数；鼓励营销链接包含 ?ref=、?utm_source=、?utm_medium=、?utm_campaign=、?utm_term= 和 ?utm_content。
• 使用筛选器按国家、设备、营销活动、URL 路径或自定义目标细分数据；将鼠标悬停在图表上可显示筛选快捷方式。
• 提供 datafast_ignore localStorage 的文档，以排除内部流量。

代理与托管指南

• 通过代理转发请求，使脚本从你域名下的 /js/script.js 加载，事件则发送至 /api/events。
• 使用 x-datafast-real-ip 转发访客 IP，以确保地理位置准确。
• Next.js 重写规则、Express HTTP 代理、Flask/FastAPI 路由、PHP 脚本、Nginx/Caddy 规则、Firebase Functions 以及 DigitalOcean/Nginx 示例都是现成方案，可根据你的技术栈选用。
• 使用 data-allowed-hostnames="app.io,shop.example.com" 将其他域名加入允许列表，并将 data-domain 设置为根域名，以便在子域名之间共享 Cookie。
• 需要自定义路由时，使用 data-api-url 或 datafast_events 端点；跟踪器会自动检测代理设置。

API 与导入/导出

• DataFast API（Overview、Timeseries、Devices、Pages、Countries、Referrers、Campaigns、Goals、Payments、Visitors、Metadata、Realtime）都需要 Authorization: Bearer <API_KEY>。
• 使用 Payments API 从不受支持的服务商推送收入：包含 amount、currency、transaction_id 和访客 ID。
• 使用 Goals API 记录服务端事件（最多 10 个元数据键）。
• 将 Plausible 导出数据导入 DataFast，以保留历史数据；参阅 Import your Plausible data。
• 通过 API Playground、Real-time 端点或自定义脚本将数据导出至仪表板。

移动端与支持

• 安装 DataFast 移动应用（iOS/Android），随时随地监控指标；使用 API 密钥连接任意网站。
• 使用 Google Search Console 集成了解关键词的影响；确保你的域名已通过验证，且你拥有所有者/完整权限。
• 在仪表板中跟踪 GitHub 提交记录，以便将版本发布与收入激增关联起来。
• 如需帮助、功能请求或故障排查，请联系 [email protected] 或访问 https://feedback.datafa.st/。

故障排查清单

• 脚本未在页头触发？确认标签位于 <head> 内，且 data-website-id 域名与 data-domain 匹配。
• 没有收入？检查支付服务商连接，以及 Stripe/LemonSqueezy/Polar 会话中的元数据 Cookie。
• 未记录目标？确保目标名称使用小写字母/下划线/连字符，且长度不超过 64 个字符。
• Vercel 预览环境没有数据显示？在暂存环境中启用 data-allow-localhost="true"，或在生产环境中使用代理脚本。
• 代理显示的访客 IP 全部为服务器 IP？添加 x-datafast-real-ip 或转发 X-Forwarded-For。

参考资料

• 脚本配置参考：data-allowed-hostnames、data-api-url、data-allow-localhost、data-disable-console、data-debug。
• 收入归因指南（Stripe Checkout、PaymentIntent、Checkout Links、LemonSqueezy、Polar、Paddle、Dodo Payments、Easytool）。
• 针对特定技术的安装文档，涵盖 Shopify、Webflow、Wix、Ghost、Next.js、Astro、Laravel、React Router、Firebase、Astro 中间件、Caddy、Nginx、DigitalOcean 等。