# 追踪事件 (https://talivia.com/zh-CN/docs/track-events)



自定义事件适合追踪比页面浏览更重要的操作，例如注册、点击结账、申请演示、打开外部链接和完成激活步骤。

## HTML 属性 [#html-属性]

为元素添加 `data-talivia-event`：

```html
<button data-talivia-event="signup-click">Start free trial</button>
```

使用 `data-talivia-event-*` 属性添加事件数据：

```html
<button
  data-talivia-event="checkout-click"
  data-talivia-event-plan="pro"
  data-talivia-event-location="pricing"
>
  Checkout
</button>
```

点击时，Talivia 会自动读取这些属性。

## 元素进入可见区域时追踪 [#元素进入可见区域时追踪]

为重要元素添加 `data-talivia-visible`，例如价格区域、行动按钮、横幅、提醒或弹窗。

```html
<section data-talivia-visible="pricing-seen">
  <h2>Simple pricing</h2>
</section>
```

当元素 50% 的区域进入可见范围时，Talivia 会在每次页面浏览中发送一次 `pricing-seen` 事件。

如果默认值不适合该元素，可使用以下可选属性：

```html
<button
  data-talivia-visible="signup-cta-seen"
  data-talivia-visible-threshold="0.7"
  data-talivia-visible-delay="700"
>
  Start free trial
</button>
```

* `data-talivia-visible-threshold` 可设为 `0.1` 到 `1`，默认值为 `0.5`。
* `data-talivia-visible-delay` 要求元素持续可见指定时长后再发送事件，默认值为 `0` 毫秒。

### 可见性事件数据 [#可见性事件数据]

每个可见性事件都包含以下数值属性：

| 属性                      |    示例 | 含义                                |
| ----------------------- | ----: | --------------------------------- |
| `visibility_percentage` |  `80` | 事件发送时元素实际可见的比例，取值范围为 `0` 到 `100`。 |
| `threshold`             | `0.7` | 触发事件所需的可见比例，取值范围为 `0.1` 到 `1`。    |
| `delay`                 | `700` | 元素在事件发送前必须保持持续可见的时长，单位为毫秒。        |

对于上面的示例，Talivia 会发送相当于以下内容的事件数据：

```json
{
  "visibility_percentage": 80,
  "threshold": 0.7,
  "delay": 700
}
```

`threshold` 和 `visibility_percentage` 使用不同的数值范围：`0.7` 表示 70% 的触发阈值，实际观测值则存储为 `70` 或更高。`delay` 表示元素必须持续可见的时长，并不是时间戳。这些属性与其他事件数据一样，可用于会话、目标和[转化漏斗](https://talivia.com/zh-CN/docs/funnels#%E7%AD%9B%E9%80%89%E4%BA%8B%E4%BB%B6%E6%AD%A5%E9%AA%A4)。

## 链接 [#链接]

对于普通链接，Talivia 会尽可能等待事件请求发出后再跳转。

```html
<a href="/pricing" data-talivia-event="pricing-link">Pricing</a>
```

外部链接、配合修饰键的点击以及 `_blank` 链接不会被延迟。

## JavaScript [#javascript]

```js
window.talivia.track('invite-sent', {
  role: 'viewer',
});
```

事件取决于应用状态、表单结果或服务器响应时，请使用 JavaScript。

## 事件数据建议 [#事件数据建议]

* 使用 `signup-click` 之类稳定的名称，不要使用会变化的按钮文案。
* 以后需要进行数值比较时，请将数值保留为数字类型。
* 除非付款归因确实需要且符合您的隐私政策，否则请勿发送个人信息。