框架与采集域名

先安装控制台提供的 tgz；公共 npm 发布后，可用 npm install @antdock/tracker。包名与域名独立，所有示例显式指定长期保留的采集地址。不要同时安装 Script 和 npm 两份 tracker。

React / Next.js App Router

在根布局中挂载一次客户端组件。SDK 自动监听 history 与 Hash 路由，不再在 pathname effect 中补发 PV。

'use client'
import { useEffect } from 'react'
import { createTrackerIntegration } from '@antdock/tracker/integration'

const analytics = createTrackerIntegration({
  appId: 'YOUR_APP_ID', endpoint: 'https://YOUR_COLLECTOR',
  release: 'YOUR_RELEASE', consentRequired: true,
})
export default function Analytics() {
  useEffect(() => analytics.mount(), [])
  return null
}
// CMP 确认后：analytics.tracker.setConsent(true)
// 拒绝或撤回：analytics.tracker.setConsent(false)

工厂在 SSR 时不操作 DOM、标识或网络。适配器计数挂载者，兼容 Strict Mode 清理和重挂载。应用级初始化配置保持稳定；不要随每个页面创建一个实例。

Vue / Nuxt

// 放在应用根组件；Nuxt 也可放在 .client.ts 插件中。
import { onMounted, onUnmounted } from 'vue'
import { createTrackerIntegration } from '@antdock/tracker/integration'
const analytics = createTrackerIntegration({ appId: 'YOUR_APP_ID', endpoint: 'https://YOUR_COLLECTOR' })
let stop: (() => void) | undefined
onMounted(() => { stop = analytics.mount() })
onUnmounted(() => stop?.())

Svelte / SvelteKit

<script lang="ts">
  import { onMount } from 'svelte'
  import { createTrackerIntegration } from '@antdock/tracker/integration'
  const analytics = createTrackerIntegration({ appId: 'YOUR_APP_ID', endpoint: 'https://YOUR_COLLECTOR' })
  onMount(() => analytics.mount())
</script>

Astro、普通 HTML 与 GTM

控制台一键复制的 Script 放在网站公共布局中一次。GTM 使用 Custom HTML，触发 All Pages 一次；同意要求开启时先暂存 init，并由 CMP 显式调用 setConsent。自动路由已开启时不要再用 History Change 标签发送 PV。Script 支持 data-spa-routing、data-release、data-breadcrumbs 与 data-long-tasks。

自己的网站做第一方代理

以 Nginx 为例，用与网站相同域的 /telemetry/ 转发到 AntDock；SDK 将 endpoint 设为 https://你的站点/telemetry。Script 安装地址为 /telemetry/static/tracker.js，必须设置 data-endpoint="https://你的站点/telemetry" 或使用控制台完整 init 代码。

location /telemetry/ {
    proxy_pass https://antdock.com/;
    proxy_ssl_server_name on;
    proxy_set_header Host antdock.com;
    proxy_set_header Cookie "";
    proxy_set_header Authorization "";
    proxy_hide_header Set-Cookie;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

SDK 配置接口和采集请求不要缓存。服务器只信任配置过的代理链；自行部署需维护 TRUSTED_PROXIES，不能信任浏览器伪造的 X-Forwarded-For。第三方客户代理不应获得全局可信 IP 权限；必要时不使用代理转发的原始 IP。

品牌域名、采集域名、npm 包名是三个独立设置。服务端 TRACKING_URL / 控制台 brandingTrackingUrl 统一生成一键复制代码。迁移时先让新地址提供同样的脚本、配置和采集接口，再改此设置并更新自己的站点。仍使用旧代码时，旧域名直接代理，避免用跳转承接 Beacon。域名与 DNS 权属未明确前不自动注册或替换域名。