> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Clarity

> Kết nối Microsoft Clarity để agent trả lời câu hỏi về lưu lượng, mức độ tương tác và lấy các bản ghi phiên tương ứng

Kết nối một project Microsoft Clarity để agent CloudThinker trả lời câu hỏi về lưu lượng, mức độ tương tác và tín hiệu gây khó chịu cho người dùng, đồng thời liệt kê các bản ghi phiên đứng sau những tín hiệu đó. Kết nối đăng nhập bằng một **API token** của Clarity (secret key thuộc về một project Clarity duy nhất) và chỉ đọc dữ liệu.

## Điều kiện tiên quyết

* Một project Clarity đang thu thập dữ liệu từ website của bạn.
* Vai trò **Admin** trên project Clarity đó, để bạn có thể tạo API token.
* Vai trò **Admin** trong workspace CloudThinker, vai trò có quyền thêm và sửa kết nối. Xem [Vai trò](https://docs.cloudthinker.io/vi/guide/security/roles.md).

## Thiết lập

**1. Tạo API token trong Clarity**

Đăng nhập Clarity, mở project và vào **Settings → Data Export**. Nhấn **Generate new API token** và đặt tên là `cloudthinker`. Tên dài từ 4 đến 32 ký tự và không có khoảng trắng.

Sao chép token ngay và giữ ở nơi an toàn cho đến bước tiếp theo.

**2. Mở Microsoft Clarity trong CloudThinker**

Trong thanh bên, nhấn **More → Workspace settings → Connections**. Trên tab **Builtin Connections**, tìm **Microsoft Clarity** và nhấn **Connect**.

**3. Dán token và kết nối**

Dán token vào **CLARITY\_API\_TOKEN** (hộp thoại hiển thị trường với đúng tên này) và nhấn **Connect**.

**Trạng thái thành công:** hộp thoại **Connect Microsoft Clarity** đóng lại và kết nối hiển thị **Connected**.

> [!NOTE]
>
> Clarity chỉ kiểm tra token khi agent dùng token lần đầu. Token gõ sai hoặc đã bị thu hồi vẫn có thể hiển thị **Connected**, nên hãy chạy prompt xác minh bên dưới trước khi dựa vào kết nối.

## Chi tiết kết nối

| Trường | Mô tả | Ví dụ |
| - | - | - |
| **CLARITY\_API\_TOKEN** | API token được tạo trong **Settings → Data Export** của project Clarity | `<your-api-token>` |

Mỗi token chỉ áp dụng cho một project. Để truy cập project Clarity thứ hai, tạo token ở project đó và kết nối riêng.

Để thay token đã lưu, mở **More → Workspace settings → Connections**, chọn **Microsoft Clarity** và nhấn biểu tượng bút chì (**Edit**) trên hàng của kết nối. Trong **Edit Instance**, nhấn **Replace…** dưới **Credentials**, dán token mới và nhấn **Save and test**.

## Quyền yêu cầu

Token có thể đọc analytics và bản ghi phiên của project đã cấp token, và không đọc được gì khác. Clarity không có scope theo từng token, nên bạn kiểm soát quyền truy cập bằng cách chọn project nào cấp token và ai được phép tạo token.

> [!TIP]
>
> Tạo một token chỉ dành cho CloudThinker. Khi đó bạn có thể thu hồi token trong Clarity mà không làm hỏng công cụ nào khác đang đọc cùng project.

## Khả năng của agent

CloudThinker dùng Clarity MCP server của Microsoft (Model Context Protocol, một cách chuẩn để agent gọi công cụ). Mọi công cụ đều chỉ đọc.

| Khả năng | Agent có thể làm gì |
| - | - |
| **Dashboard analytics** | Hỏi về phiên, người dùng, trang phổ biến, nguồn giới thiệu, kênh và chiến dịch, phân theo thiết bị, trình duyệt, hệ điều hành hoặc quốc gia |
| **Behavior and performance** | Báo cáo độ sâu cuộn trang, dead click, rage click, quick back, lỗi JavaScript và Core Web Vitals |
| **Session recordings** | Liệt kê bản ghi phiên lọc theo ngày, URL trang, thiết bị, trình duyệt, hệ điều hành, quốc gia, UTM source hoặc tín hiệu khó chịu, sắp xếp theo thời điểm bắt đầu, thời lượng, số lần nhấn hoặc số trang. Tối đa 250 mỗi yêu cầu |

Agent cũng có thể tra cứu tài liệu của chính Clarity, ví dụ cách custom event hoạt động.

Câu hỏi về dashboard chỉ bao quát 1 đến 3 ngày gần nhất (24, 48 hoặc 72 giờ), vì API của Clarity chỉ trả về chừng đó. Hãy hỏi "3 ngày gần nhất" hoặc ngắn hơn, và dùng dashboard Clarity cho khoảng thời gian dài hơn. Clarity trả lời tốt nhất khi mỗi truy vấn có một metric, nên CloudThinker tách câu hỏi rộng thành nhiều truy vấn. Mỗi truy vấn là một lệnh gọi riêng đến API của Clarity, vốn chỉ cho phép 10 lệnh gọi dashboard mỗi project mỗi ngày, nên câu hỏi hẹp sẽ dùng được lâu hơn.

### Xác minh kết nối

```text theme={null}
How many Clarity sessions did we get in the last 3 days, broken down by device type?
```

Kết nối hoạt động sẽ trả về số phiên thực cho **PC**, **Mobile** và **Tablet**. Nếu nhận được lời giải thích chung chung về Clarity hoặc lỗi ủy quyền, token đang sai.

### Ví dụ prompt

```text theme={null}
Which 5 pages had the most rage clicks in Clarity over the last 3 days?
List the 10 longest Clarity sessions from mobile devices yesterday that hit a JavaScript error
Compare average scroll depth on mobile and desktop for /pricing over the last 2 days
```

## Khắc phục sự cố

> **Đã kết nối, nhưng mọi yêu cầu đều thất bại với lỗi ủy quyền**
>
> Clarity đã từ chối token. Token có thể đã bị thu hồi, gõ sai hoặc do project khác cấp. Tạo token mới trong đúng project, mở kết nối và thay token đã lưu.

> **This connection did not respond in time. Try connecting again.**
>
> CloudThinker không thể khởi động Clarity server trước khi hết thời gian chờ. Nhấn **Connect** lần nữa. Nếu vẫn hết thời gian chờ, kiểm tra Clarity có tải được cho project của bạn không, rồi gửi email đến [support@cloudthinker.io](mailto:support@cloudthinker.io) kèm thời điểm xảy ra lỗi.

> **Câu trả lời dừng giữa chừng, hoặc Clarity báo giới hạn tốc độ**
>
> Clarity cho phép 10 lệnh gọi dashboard mỗi project mỗi ngày, và một câu hỏi rộng dùng nhiều lệnh gọi. Đợi đến ngày hôm sau, rồi hỏi từng metric và từng cách phân loại một.

> **Kết quả bao quát sai ngày**
>
> Câu hỏi về dashboard chỉ lùi lại được 1 đến 3 ngày, nên câu hỏi về tuần hoặc tháng trước chỉ trả về tối đa 3 ngày gần nhất. Dùng dashboard Clarity cho khoảng thời gian dài hơn. Clarity cũng báo cáo theo UTC, nên "hôm qua" tính theo UTC chứ không theo giờ địa phương. Hãy đưa ra khoảng ngày cụ thể, hoặc nêu múi giờ trong prompt.

> **Câu trả lời mơ hồ hoặc trộn nhiều metric**
>
> Clarity trả lời tốt nhất khi mỗi truy vấn có một metric. Hãy hỏi một metric, một cách phân loại và một khoảng thời gian cụ thể, rồi tiếp tục với câu hỏi tiếp theo.

## Bảo mật

* **Quyền tối thiểu** — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
* **Chỉ đọc theo mặc định** — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
* **Xoay vòng thông tin xác thực** — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
* **Thu hồi khi bàn giao** — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.

- **Thay token khi có người rời đi.** Khi người có quyền truy cập project Clarity rời đi, hãy tạo token mới và thay token đã lưu.
- **Không đưa token vào chat.** Chỉ dán token vào hộp thoại kết nối, không bao giờ vào tin nhắn chat hay repository.

## Liên quan

> **[Kết nối PostHog](https://docs.cloudthinker.io/vi/guide/connections/posthog.md)**
>
> Thêm product analytics, feature flag và theo dõi lỗi bên cạnh Clarity

> **[Tổng quan kết nối](https://docs.cloudthinker.io/vi/guide/connections/overview.md)**
>
> Xem cách quyền truy cập, thao tác ghi và xoay vòng thông tin xác thực hoạt động cho mọi kết nối


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.