DataFast 技能用于在任意技术栈上接入 DataFast 网站分析与营收归因功能，把安装、归因、事件、代理和 API 使用模式固化下来，便于可靠地采用 DataFast。
一、适用场景 当需要为网站（静态、SPA、Next.js、Astro 等）接入 DataFast 跟踪；当需要将营收归因到营销渠道（Stripe、LemonSqueezy、Polar、自定义服务商）；当希望在广告拦截环境下仍可靠记录自定义事件/目标；当需要代理跟踪脚本以提升数据质量或支持哈希导航；当需要导出/导入历史分析数据或查询 DataFast API 时，均可使用本技能。
二、快速开始（四步）
- 在 <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 片段，用于在库加载前排队调用。
- 在 Revenue 标签页连接支付服务商（Stripe、LemonSqueezy、Polar、Shopify 等），让 DataFast 自动追踪营收。
- 通过 window.datafast("my_goal")、data-fast-goal 属性或服务端 Goals API 添加自定义目标/事件。 可选：设置代理以绕过广告拦截，将 /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 / 自定义：调用 Payments API 或使用客户邮箱触发支付目标。 对于 DataFast 已自动拉取营收的网关（Shopify、Stripe、LemonSqueezy、Polar），保留跟踪片段但省略冗余的手动事件。应记录 metadata 映射，并确保下游任务对每个财务事件读取 datafast_visitor_id。
五、自定义事件与目标 方法一——window.datafast()（客户端）：在点击、成功页或 API 响应后触发 window?.datafast("goal_name")；可记录参数，如 window.datafast("checkout", { price: "49", plan: "pro" })。 方法二——HTML data 属性：为按钮/链接添加 data-fast-goal="goal_name"；可用 data-fast-goal-* 属性补充信息（data-fast-goal-price="49" 会变成 { price: "49" }）。 方法三——服务端 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 rewrites、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 处理服务端事件（metadata 最多 10 个键）。可将 Plausible 导出数据导入 DataFast 以保留历史数据，参考《Import your Plausible data》。可通过 API Playground、实时端点或自定义脚本导出到仪表盘。
九、移动端与支持 安装 DataFast 移动应用（iOS/Android）随时监控指标；用 API key 连接任意站点。使用 Google Search Console 集成了解关键词影响；确保域名已验证并拥有 owner/完整权限。在仪表盘追踪 GitHub 提交，将发布与营收峰值关联。可通过 marc@datafa.st 或 https://feedback.datafa.st/ 获取帮助、提出功能请求或进行故障排查。
十、故障排查清单
- 脚本未在响应头触发？确认标签位于 <head> 内，且 data-website-id 与 data-domain 匹配。
- 没有营收？检查支付服务商连接，以及 Stripe/LemonSqueezy/Polar 会话中的 metadata cookie。
- 目标未记录？确保目标名称使用小写/下划线/连字符且不超过 64 个字符。
- Vercel 预览无数据？在预发环境启用 data-allow-localhost="true"，或依赖生产环境的代理脚本。
- 代理显示所有访客来自服务器 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 middleware、Caddy、Nginx、DigitalOcean 等提供技术专属安装文档。
价格、收费方式以及平台支持范围等细节，资料暂未提供。