API công khai & khóa API

1. Tổng quan

API MousePlayer cho phép lấy dữ liệu từ không gian làm việc vào bảng điều khiển, kho dữ liệu hoặc công cụ nội bộ của bạn. Ngoài việc gắn ID khách hàng vào phiên (identify, cần khóa có phạm vi ghi, xem Phạm vi khóa), API chỉ đọc: không thể sửa hoặc xóa dữ liệu qua API.

• URL cơ sở: https://www.mouseplayer.com/api/v1/
• Mọi phản hồi đều là JSON.
• Mọi yêu cầu được xác thực bằng khóa API và tự giới hạn trong không gian làm việc của khóa — khóa của một không gian làm việc không bao giờ thấy dữ liệu của không gian khác, kể cả vô tình.
• Bản ghi phát lại phiên đầy đủ (di chuyển chuột, ảnh chụp DOM) không được cung cấp qua API. Bạn nhận siêu dữ liệu phiên, lượt xem trang, sự kiện tùy chỉnh và phân khúc — đủ để xây dựng báo cáo và bảng điều khiển mà không chuyển payload phát lại thô đi khắp nơi.

2. Xác thực

Tạo và quản lý khóa API trong mục Khóa API trên menu tài khoản (/api-keys). Chỉ chủ sở hữu và quản trị viên không gian làm việc có thể tạo hoặc thu hồi khóa.

Gửi khóa dưới dạng token Bearer trong tiêu đề Authorization của mọi yêu cầu:

Khóa thiếu, sai định dạng hoặc đã thu hồi nhận phản hồi 401:

Yêu cầu về gói

REST API là một phần của các gói Business và Enterprise. Gói được lấy từ chủ sở hữu không gian làm việc nên thành viên được mời kế thừa. Kiểm tra chạy trên mọi yêu cầu, không chỉ khi tạo khóa — nếu không gian làm việc hạ gói, khóa hiện có ngừng hoạt động và trả 403.

Phạm vi khóa

Mọi khóa mang phạm vi trong tiền tố nên chỉ cần nhìn là biết khóa làm gì — trong .env, trong phiếu hoặc trong terminal.

3. Giới hạn tần suất

Mỗi khóa API giới hạn 60 yêu cầu mỗi phút, theo cửa sổ trượt. Vượt giới hạn, yêu cầu nhận phản hồi 429 cho đến khi cửa sổ được giải phóng:

4. Điểm cuối

GET/api/v1/projects

Liệt kê mọi dự án (thuộc tính được theo dõi) trong không gian làm việc.

GET/api/v1/projects/{channelid}/sessions

Liệt kê phiên khách được ghi cho dự án, mới nhất trước. Có phân trang.

GET/api/v1/sessions/{session_id}

Siêu dữ liệu của một phiên cùng các lượt xem trang. Chủ động không gồm payload phát lại đầy đủ — dùng trình phát trong bảng điều khiển để xem.

GET/api/v1/sessions/{session_id}/events

Sự kiện tùy chỉnh kích hoạt trong phiên (cùng sự kiện bạn gửi bằng mp('event', ...)), gồm các tham số.

GET/api/v1/projects/{channelid}/segments

Liệt kê phân khúc khách được định nghĩa cho dự án (cả riêng dự án và toàn không gian làm việc).

5. Gắn ID khách hàng từ hệ thống phía sau

Trình duyệt thường không biết ai đang ngồi đó. Với sản phẩm B2B, danh tính được xác định sau đăng nhập — trong hệ thống phía sau của bạn. Với cửa hàng, khi xác nhận đơn hàng. Điểm cuối này dành cho đúng thời điểm đó.

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

ID xuất hiện trong danh sách phiên, tìm kiếm được tại đó và webhook session_identified kích hoạt — nhờ đó đến CRM.

6. Webhook: xác minh chữ ký

Webhook được cấu hình theo dự án tại Tích hợp, nơi có khóa bí mật ký. Mỗi lần gửi có các tiêu đề:

Chữ ký là HMAC-SHA256 trên timestamp + "." + raw body với khóa bí mật ký của dự án.

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

Gửi và thử lại

Lần gửi thất bại được thử lại sau 1 phút, 5 phút, 15 phút, 1 giờ và 6 giờ rồi bỏ cuộc. Với loại 4xx, các phản hồi ngoài 408 và 429 đều không được thử lại — chúng nói "không được làm như vậy", không phải "không phải lúc này". Hãy trả 2xx nhanh rồi làm việc sau; lần gửi hết thời gian chờ sau 10 giây.

Sự kiện có sẵn

7. Lỗi & mã trạng thái

8. Lưu ý bảo mật

• Khóa chỉ đọc (mp_ro_) không thay đổi được gì. Khóa ghi (mp_rw_) chỉ gắn ID khách hàng; không khóa nào xóa dữ liệu hoặc xuất dữ liệu phát lại thô.
• Mọi yêu cầu tự giới hạn trong không gian làm việc của khóa — không có cách truyền ID không gian làm việc khác để xem dữ liệu người khác.
• Thu hồi khóa bất cứ lúc nào tại /api-keys; có hiệu lực ngay lập tức.
• Coi khóa API như mật khẩu. Nếu vô tình commit vào kho mã công khai, thu hồi ngay rồi tạo khóa mới.