Đ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ò.
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.
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
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.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.
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
Ví dụ prompt
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
Đã 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.
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 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 độ
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
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
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
Thêm product analytics, feature flag và theo dõi lỗi bên cạnh Clarity
Tổng quan kết nối
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