# 追踪器配置 (https://talivia.com/zh-CN/docs/tracker-configuration)



追踪器会读取脚本标签上的 `data-*` 属性。对于常规 Talivia 云服务安装，请从**设置 → 数据追踪**复制完整代码片段，并保持生成的属性不变。

```html
<script
  defer
  src="https://talivia.com/script.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-domain="example.com"
  data-auto-track="true"
></script>
```

只追踪一个主机名时，仅 `data-website-id` 为必填项。Talivia 云服务通常也会生成 `data-domain`；保留它是安全的，并可让多个子域名延续同一匿名身份。

## 域名属性 [#域名属性]

下面几个名称相似的属性分别解决不同问题：

| 属性                          | 用途                                                                      |
| --------------------------- | ----------------------------------------------------------------------- |
| `data-domain`               | 设置 Cookie 范围。当同一访客会在 `example.com` 与其子域名之间移动时，请使用 `example.com` 这样的根域名。 |
| `data-domains`              | 限制允许此脚本采集数据的主机名，不会用于共享身份。                                               |
| `data-cross-domain-domains` | 使用签名连接令牌，在 `example.com` 与 `example.net` 等不同根域名之间延续访问路径。                |

网站只运行在一个主机名上时，无需手动配置域名。子域名请参阅[子域名追踪](https://talivia.com/zh-CN/docs/subdomain-tracking)，不同根域名请参阅[跨域追踪](https://talivia.com/zh-CN/docs/cross-domain-tracking)。

## 可用属性 [#可用属性]

| 属性                          | 说明                                               |
| --------------------------- | ------------------------------------------------ |
| `data-website-id`           | 必填的网站编号。                                         |
| `data-host-url`             | 自行托管或使用自定义反向代理时覆盖数据采集接口来源。常规 Talivia 云服务安装请勿设置。  |
| `data-domain`               | 网站及其子域名共享的可选 Cookie 域名。Talivia 云服务会根据已配置的网站域名生成。 |
| `data-auto-track`           | 设为 `false` 可关闭首次自动页面浏览。                          |
| `data-domains`              | 可选的逗号分隔主机名允许列表。共享身份时无需逐一列出子域名。                   |
| `data-cross-domain-domains` | 允许接收 Talivia 签名连接令牌的逗号分隔根域名。                     |
| `data-do-not-track`         | 设为 `true` 可遵循浏览器的“请勿追踪”设置。                       |
| `data-exclude-search`       | 设为 `true` 可在发送网址前移除查询字符串。                        |
| `data-exclude-hash`         | 设为 `true` 可在发送网址前移除井号片段。                         |
| `data-tag`                  | 为此脚本发送的每个事件附加标签。                                 |
| `data-before-send`          | 可修改或取消负载的全局函数名。                                  |
| `data-fetch-credentials`    | Fetch 凭据模式，默认为 `omit`。                           |
| `data-performance`          | 设为 `true` 可采集网页核心性能指标。                           |

## beforeSend [#beforesend]

```html
<script>
  window.taliviaBeforeSend = (type, payload) => {
    if (payload.url?.includes('/internal-preview')) return null;

    return payload;
  };
</script>

<script
  defer
  src="https://talivia.com/script.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-before-send="taliviaBeforeSend"
></script>
```

返回 `null` 或 `undefined` 即可取消事件。

## 域名允许列表 [#域名允许列表]

这是可选限制，并非子域名追踪的必要条件。

```html
<script
  defer
  src="https://talivia.com/script.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-domains="example.com"
></script>
```

一个根域名条目会覆盖该域名及其子域名。当同一布局可能显示在预发布、预览和生产域名上时，此限制很有用。

## 数据采集主机 [#数据采集主机]

脚本会自动把数据发送到 Talivia 云服务。`data-host-url` 只适用于自行托管和自定义反向代理，即浏览器必须将采集请求发送到其他来源的情况。它不是被追踪网站的附加网址，常规云服务代码片段中应省略。

## 身份存储 [#身份存储]

Talivia 将匿名访客标识符和滚动会话标识符保存在第一方 Cookie 中。

## 访客与会话有效期 [#访客与会话有效期]

* 匿名访客 Cookie 的有效期为 365 天。
* 会话 Cookie 的有效期为 30 分钟，追踪器每次发送活动时都会刷新。
* 关闭标签页不会拆分仍在活动的会话。所有标签页和已配置子域名都会重复使用同一个滚动会话。

多个子域名需要共享身份时，请将 `example.com` 这样的可注册根域名用于 `data-domain`，不要使用 `app.example.com`。手动修改前，请从**设置 → 数据追踪**复制生成的代码片段并阅读[子域名追踪](https://talivia.com/zh-CN/docs/subdomain-tracking)。

## 敏感查询参数 [#敏感查询参数]

Talivia 会从存储的网址查询中移除 OAuth 凭据、签名跨域令牌和结账会话编号。付款返回检测会在清理之前运行，因此 Stripe 及其他结账归因仍可正常工作，同时不会在分析数据中显示机密信息。