Публичен 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 е част от плановете Бизнес и Корпоративен. Планът се взема от собственика на работното пространство, така че поканените членове го наследяват. Проверката се изпълнява при всяка заявка, не само при създаване на ключ — ако работното пространство премине към по-нисък план, съществуващите ключове спират да работят и връщат 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}}

След това идентификаторът се появява в списъка със сесии, може да се търси там и се задейства webhook session_identified — така достига до CRM системата ви.

6. Webhook заявки: проверка на подписа

Webhook заявките се конфигурират за всеки проект под Интеграции, където е и тайната за подписване. Всяко доставяне съдържа тези заглавки:

Подписът е 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 като към парола. Ако случайно го включите в публично хранилище, отменете го незабавно и създайте нов.