Публічний API & ключі API

1. Огляд

API MousePlayer дає змогу отримувати дані з робочого простору для власних панелей показників, сховища даних чи внутрішніх інструментів. Окрім додавання ідентифікаторів клієнтів до сеансів (identify, потрібен ключ із правом запису, див. «Області доступу ключів»), він працює лише для читання: через API неможливо змінити чи видалити дані.

• Базовий URL: https://www.mouseplayer.com/api/v1/
• Усі відповіді у форматі JSON.
• Кожен запит автентифікується ключем API й автоматично обмежується робочим простором цього ключа — ключ одного простору ніколи не побачить даних іншого, навіть випадково.
• Повний запис для відтворення сеансу (рухи миші, знімки DOM) не надається через API. Ви отримуєте метадані сеансів, перегляди сторінок, власні події й сегменти — достатньо для звітів і панелей показників без передавання необроблених даних відтворення.

2. Автентифікація

Створюйте ключі API й керуйте ними в розділі Ключі API меню облікового запису (/api-keys). Створювати й відкликати ключі можуть лише власники й адміністратори робочого простору.

Передавайте ключ як токен Bearer у заголовку Authorization кожного запиту:

За відсутнього, некоректного чи відкликаного ключа повертається відповідь 401:

Вимога до тарифу

REST API входить до тарифів Business та Enterprise. Тариф визначається за власником робочого простору, тож запрошені учасники команди успадковують його. Перевірка виконується для кожного запиту, а не лише під час створення ключа — якщо тариф робочого простору знижено, наявні ключі перестають працювати й повертають 403.

Області доступу ключів

Кожен ключ містить свою область доступу у власному префіксі, тож його можливості видно з самого ключа — у .env, заявці чи терміналі.

3. Обмеження частоти запитів

Кожен ключ API обмежено 60 запитами на хвилину із підрахунком у ковзному вікні. Після перевищення запити отримують відповідь 429 до звільнення вікна:

4. Кінцеві точки

GET/api/v1/projects

Перелічує всі проєкти (відстежувані сайти) вашого робочого простору.

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

Перелічує записані сеанси відвідувачів проєкту, спочатку найновіші. Є поділ на сторінки.

GET/api/v1/sessions/{session_id}

Метадані одного сеансу та його перегляди сторінок. Повні дані відтворення навмисно не включено — для них використовуйте плеєр панелі показників.

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

Власні події, що відбулися під час сеансу (ті самі події, які ви надсилаєте через mp('event', ...)), разом із параметрами.

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

Перелічує сегменти відвідувачів, визначені для проєкту (як проєктні, так і спільні для робочого простору).

5. Додавання ідентифікатора клієнта із сервера

Браузер часто не знає, хто перед ним. У продукті B2B ідентичність установлюється після входу — на вашому сервері. У магазині — під час підтвердження замовлення. Ця кінцева точка призначена саме для цього моменту.

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}}

Тоді ідентифікатор з’являється в списку сеансів, стає доступним для пошуку, а вебхук session_identified спрацьовує — так він і потрапляє до CRM.

6. Вебхуки: перевірка підпису

Вебхуки налаштовуються для кожного проєкту в розділі Інтеграції, де також міститься секрет підписування. Кожна доставка має такі заголовки:

Підпис — це HMAC-SHA256 від timestamp + "." + raw body із секретом підписування вашого проєкту як ключем.

// 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');

Доставка й повторні спроби

Невдала доставка повторюється через 1 хв, 5 хв, 15 хв, 1 год і 6 год, після чого спроби припиняються. 4xx відповіді, окрім 408 та 429 , повторно не надсилаються — вони кажуть "не так", а не "не зараз". Відповідайте 2xx швидко, а роботу виконуйте потім; тайм-аут доставки — 10 секунд.

Доступні події

7. Помилки & коди статусу

8. Примітки щодо безпеки

• Ключі лише для читання (mp_ro_) нічого не можуть змінювати. Ключі запису (mp_rw_) можуть лише додавати ідентифікатори клієнтів; жоден ключ не може видаляти дані чи експортувати необроблені дані відтворення.
• Кожен запит автоматично обмежено власним робочим простором ключа — неможливо передати ідентифікатор іншого простору й побачити чужі дані.
• Відкликайте ключ будь-коли в розділі /api-keys; відкликання діє негайно.
• Поводьтеся з ключем API як із паролем. Якщо випадково додасте його до публічного репозиторію, негайно відкличте й створіть новий.