开发者 · 无需登录

接入文档

嵌入追踪脚本、v1 采集协议与自定义事件说明。站点 UUID 与带真实 ID 的嵌入代码请在管理后台「网站设置」中复制（需管理员 token）。

快速开始

在管理后台「网站设置」新建站点，记下站点 UUID 与业务域名（用于 data-domains）。
将下方脚本中的 YOUR_WEBSITE_ID 与域名换成你的值；确认 data-host 指向采集 API（通常与 tracker_origin 一致）。
粘贴到业务站 <head> 或 <body> 末尾，建议 defer。
打开业务页，在控制台「实时」或「访问明细」确认有 pageview。

嵌入代码（模板）

以下为公开模板；登录后在「网站设置」编辑站点时可复制已填好 UUID 的完整代码。

<script defer src="https://analyze.demo2easy.com/script.js" data-website="YOUR_WEBSITE_ID" data-host="https://analyze.demo2easy.com" data-domains="www.example.com" data-do-not-track="true"></script>

脚本地址：https://analyze.demo2easy.com/script.js · 采集端点：https://analyze.demo2easy.com/api/send

script 标签属性

字段	必填	说明
src	是	追踪脚本 URL；生产环境多与仪表盘同域，由反向代理到 Rust 服务。
data-website	是	站点 UUID（控制台「网站设置」）。
data-host	否	采集 API 根地址（不含路径）；默认与 script 所在域相同，跨域部署时必填。
data-domains	否	逗号分隔 hostname 白名单；设置后仅在这些域名上上报。
data-do-not-track	否	为 "true" 时，若访客浏览器开启 DNT，则不上报。

采集 API 概览（v1）

官方脚本与自研客户端均向 POST /api/send 发送 JSON。请求必须带 User-Agent 头，否则返回 400。正文一律经 Base64 传输业务字段（防网络面板窥视，不是加密，不能防篡改）。

字段	必填	说明
type	是	仅 "event" 或 "duration"。页面浏览与自定义事件都用 "event"；没有 "pageview" 类型码。
version	是	当前为 "v1"（payload 为 Standard Base64(UTF-8 JSON)）。"v2" 预留，返回 501。
payload	是	字符串：Base64 编码后的 v1 正文 JSON（见下表）。

外层报文示例

{
  "type": "event",
  "version": "v1",
  "payload": "eyJ3ZWJzaXRlIjoiLi4uIn0="
}

批量上报：POST /api/batch，body 为上述对象的 JSON 数组；响应 { "ok": n, "failed": m }，单条失败不影响其余条目。

v1 正文 JSON 字段

对 payload 做 Base64 解码后得到的对象。字段名区分大小写（自定义事件用 camelCase eventName / eventData）。

字段	必填	说明
website	是	站点 UUID。
id	否	会话 ID；脚本写入 localStorage，缺省时服务端生成。
url	否	路径 + query（如 /blog?id=1）；缺省按 / 处理。
title	否	页面标题。
referrer	否	引荐 URL；SPA 站内跳转由脚本维护上一页 URL。
hostname	否	页面 hostname。
screen	否	如 "1920x1080"。
language	否	浏览器语言，如 "zh-CN"。
eventName	否	仅 type=event：非空表示自定义事件；省略或空字符串则记为 pageview。
eventData	否	仅自定义事件：任意 JSON 对象，入库为字符串，在访问明细展示。
duration	否	仅 type=duration：停留毫秒（1s～30min 参与统计）；更新同 session+url 最近一条 pageview。

pageview 正文示例（解码后）

{
  "website": "550e8400-e29b-41d4-a716-446655440000",
  "id": "session-uuid-from-localStorage",
  "url": "/pricing",
  "title": "价格 · 示例站",
  "referrer": "https://example.com/",
  "hostname": "www.example.com",
  "screen": "1920x1080",
  "language": "zh-CN"
}

自定义事件正文示例

{
  "website": "550e8400-e29b-41d4-a716-446655440000",
  "id": "session-uuid",
  "url": "/checkout",
  "eventName": "purchase",
  "eventData": { "amount": 99, "currency": "CNY" }
}

停留时长 ping 正文示例

{
  "website": "550e8400-e29b-41d4-a716-446655440000",
  "id": "session-uuid",
  "url": "/pricing",
  "duration": 12500
}

type 与入库类型对照

HTTP type	正文条件	行为	明细「类型」
event	无 eventName	插入 pageview	pageview
event	有 eventName	插入自定义事件	event
duration	含 duration、url	更新最近 pageview 时长，不插入新行	—

自动采集行为

脚本不依赖 Cookie；会话 ID 存在 localStorage。每次 pageview 上报路径、标题、来源、语言、屏幕、UA 解析出的浏览器/系统/设备，以及服务端 GeoIP（若配置 mmdb）。离开页面时用 sendBeacon / keepalive fetch 尽量发送停留时长。

首屏在 document.readyState === complete 后上报，并短暂等待 document.title 与 SPA 同步。
Hook history.pushState / replaceState / popstate，站内路由变化计为新 pageview。

自定义事件 track()

脚本加载后使用 window.webTracker.track(事件名, 属性?)。事件名建议 snake_case；属性映射为正文 eventData。与 pageview 一样走 type: event，由 eventName 区分。

请在脚本执行后再调用（如 DOMContentLoaded 或点击回调）。未加载时访问 window.webTracker 会报错。

事件名会出现在「自定义事件」排行；属性仅作明细参考，可自由扩展字段。

window.webTracker.track("signup", {
  plan: "pro",
  source: "pricing_page",
});

按钮或链接点击

适合统计「立即试用」「下载白皮书」等 CTA，建议带上位置或文案标识。

document.getElementById("try-free")?.addEventListener("click", () => {
  window.webTracker.track("cta_click", {
    id: "try-free",
    label: "免费试用",
    path: location.pathname,
  });
});

文件下载

window.webTracker.track("download", {
  file: "product-brochure.pdf",
  category: "marketing",
});

站内搜索

window.webTracker.track("search", {
  query: keyword.slice(0, 100),
  results: resultCount,
});

表单提交结果

window.webTracker.track("form_submit", {
  form: "contact",
  success: true,
});

下单 / 转化（示例）

请勿上报信用卡号、完整手机号等敏感信息；业务字段请自行脱敏。

window.webTracker.track("purchase", {
  order_id: "ORD-2026-001",
  amount: 99,
  currency: "CNY",
});

单页应用（SPA）

若路由变化未走 History API（极少见），可手动刷新当前页统计：

window.webTracker.trackView();

本地开发与跨域

业务站与 API 端口不同时（如 localhost:3000 → localhost:9001），设置 data-host 与 config.toml 的 tracker_origin 一致。
data-domains 须包含你访问业务站用的 hostname；勿混用 127.0.0.1 与 localhost。
Rust 服务已对 /api/send 开启 CORS，业务站无需再配代理。

常见错误

400 bad request：缺少 User-Agent、非法 type、payload 非合法 Base64/JSON、website 不存在等。
501 not implemented：version: v2 尚未开放。
有 duration 但平均停留不变：需同 session、同 url 先有一条 pageview；仅发 duration 不会新建事件。