# Theo dõi mở và nhấp

Theo dõi cho bạn biết ai đã mở email và nhấp vào link nào. Bạn bật theo từng tên miền gửi, và mọi email HTML gửi từ tên miền đó đều được theo dõi, dù gửi qua API, SMTP relay, chiến dịch email hay automation. Lượt mở và lượt nhấp hiện trên trang email trong dashboard, trong [Số liệu](https://hatang.dev/vi/docs/guides/email/metrics-and-logs.md) và qua webhook `email.opened`, `email.clicked`.

## Trước khi bắt đầu

- Một tên miền đã thêm vào Hạ Tầng. Xem [Tên miền](https://hatang.dev/vi/docs/guides/email/domains.md).
- Nếu dùng API, key có `email:write`.

## Bật theo dõi

Trong dashboard, mở **Email → Tên miền**, chọn tên miền và bật **Theo dõi mở**, **Theo dõi nhấp** ở mục **Theo dõi**. Bạn cũng có thể bật ngay khi thêm tên miền (**Tuỳ chọn nâng cao → Tuỳ chọn theo dõi**). Cả hai mặc định tắt.

**cURL**

```bash
curl -X PATCH https://api.hatang.dev/domains/$DOMAIN_ID \
  -H "Authorization: Bearer $HATANG_API_KEY" -H "Content-Type: application/json" \
  -d '{ "open_tracking": true, "click_tracking": true }'
```

**Node.js**

```ts
await hatang.domains.update({ id: domainId, open_tracking: true, click_tracking: true });
```

**Python**

```python
requests.patch(
    f"https://api.hatang.dev/domains/{domain_id}",
    headers={"Authorization": f"Bearer {os.environ['HATANG_API_KEY']}"},
    json={"open_tracking": True, "click_tracking": True},
)
```

**PHP**

```php
$client->patch("/domains/$domainId", [
    'headers' => ['Authorization' => 'Bearer ' . getenv('HATANG_API_KEY')],
    'json' => ['open_tracking' => true, 'click_tracking' => true],
]);
```

Thiết lập được chép vào từng email lúc Hạ Tầng nhận email, nên thay đổi chỉ áp dụng cho email gửi từ lúc đó. Không bật tắt theo dõi riêng cho từng email được.

## Theo dõi mở hoạt động thế nào

Hạ Tầng chèn một ảnh trong suốt 1×1 vào cuối phần HTML. Khi ứng dụng email tải ảnh này, Hạ Tầng ghi nhận một lượt mở cho người nhận đó.

- Chỉ phần HTML được theo dõi. Email chỉ có văn bản thuần không ghi nhận được lượt mở.
- Mọi lượt mở đều được lưu. Webhook `email.opened` gửi tối đa mỗi giờ một lần cho mỗi người nhận.
- Lượt mở chỉ là ước lượng. Một số ứng dụng email và cổng bảo mật tự tải ảnh dù không ai đọc thư (ví dụ Apple Mail Privacy Protection), số khác chặn ảnh, nên con số thật có thể cao hoặc thấp hơn. Hạ Tầng đánh dấu lượt mở đến từ các proxy ảnh đã biết bằng `suspected_proxy` trong dữ liệu sự kiện.

## Theo dõi nhấp hoạt động thế nào

Hạ Tầng viết lại mọi link `http` hoặc `https` trong HTML thành một địa chỉ theo dõi. Khi người nhận nhấp, Hạ Tầng ghi nhận sự kiện rồi chuyển hướng (`302`) tới URL gốc.

- Link không phải `http(s)` được giữ nguyên: `mailto:`, `tel:`, `sms:`, `#anchor`.
- Muốn giữ nguyên một link, thêm thuộc tính `data-no-track`: `<a href="https://shop.vn/tai-khoan" data-no-track>`.
- URL gốc được mã hoá bên trong link theo dõi, nên không ai sửa được để chuyển hướng sang trang khác.
- Mỗi lượt nhấp được lưu và gửi webhook `email.clicked` kèm link:

```json
{
  "type": "email.clicked",
  "created_at": "2026-10-14T09:20:11.000Z",
  "data": {
    "email_id": "0199e6c1-7a2b-7f00-9c1e-3f6a2b1d9e10",
    "from": "Shop <orders@shop.vn>",
    "to": ["lan@example.vn"],
    "subject": "Đơn #1024 đã được xác nhận",
    "created_at": "2026-10-14T09:12:03.000Z",
    "tags": {},
    "click": { "link": "https://shop.vn/don-hang/1024", "timestamp": "2026-10-14T09:20:11.000Z", "ipAddress": "203.0.113.7", "userAgent": "Mozilla/5.0 …" }
  }
}
```

Trang email trong dashboard (**Tương tác**) hiển thị số lượt mở duy nhất và tổng, cùng số lượt nhấp theo từng link.

## Dùng tên miền phụ theo dõi của bạn

Mặc định link theo dõi và pixel mở dùng máy chủ theo dõi của nền tảng. Một tên miền phụ theo dõi như `links.shop.vn` giúp chúng dùng tên miền của bạn, để link trong email khớp thương hiệu và không dùng chung máy chủ với người gửi khác.

1. Đặt nhãn tên miền phụ: khi thêm tên miền (**Tên miền phụ theo dõi**), hoặc sau đó bằng `PATCH /domains/{id}` với `{ "tracking_subdomain": "links" }`. Nhãn phải khác nhãn return path (`send`).
2. Thêm bản ghi CNAME **Theo dõi** hiển thị trên trang tên miền, ví dụ `links.shop.vn CNAME` trỏ tới máy chủ theo dõi được ghi ở đó.
3. Xác minh lại tên miền (**Kiểm tra lại DNS** hoặc `POST /domains/{id}/verify`).

Cho tới khi CNAME được xác minh, link vẫn dùng máy chủ của nền tảng (dashboard ghi rõ ở mục **Theo dõi**). Khi đã xác minh, `tracking_domain_verified` là `true` và email mới dùng `https://links.shop.vn/…`. Hạ Tầng tự lấy chứng chỉ HTTPS cho tên miền phụ. Đặt `tracking_subdomain` là `null` để quay lại máy chủ của nền tảng.

## Quyền riêng tư

- Mỗi sự kiện mở hoặc nhấp lưu người nhận, thời điểm, địa chỉ IP và user agent của request. Các thông tin này có trong webhook và trong `GET /emails/{id}/events`.
- Theo dõi mở thêm một ảnh mà ứng dụng email của người nhận tải từ Hạ Tầng. Hãy nói rõ việc theo dõi trong chính sách quyền riêng tư, và xin đồng ý khi pháp luật yêu cầu.
- Nếu không cần, hãy tắt theo dõi cho email giao dịch như đặt lại mật khẩu.
- Link trong email đặt lại mật khẩu hay đăng nhập cũng đi qua bước chuyển hướng. Thêm `data-no-track` để giữ URL nhạy cảm khỏi link theo dõi.

## Bước tiếp theo

- [Số liệu và logs](https://hatang.dev/vi/docs/guides/email/metrics-and-logs.md)
- [Webhook](https://hatang.dev/vi/docs/guides/getting-started/webhooks.md)
- [Tên miền](https://hatang.dev/vi/docs/guides/email/domains.md)

Source: https://hatang.dev/vi/docs/guides/email/tracking