Јавен API & API-клучеви

1. Преглед

API на MousePlayer ви овозможува да преземате податоци од работниот простор во сопствени контролни табли, складиште на податоци или внатрешни алатки. Освен додавање ID на клиенти во сесии (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. Додавање ID на клиент од серверскиот систем

Прелистувачот често не знае кој седи таму. Во 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}}

ID потоа се појавува во списокот на сесии, може да се пребарува таму и се активира веб-куката 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_) може само да додаваат ID на клиенти; ниту еден клуч не може да брише податоци или да извезува необработени податоци за репродукција.
• Секое барање автоматски е ограничено на работниот простор на клучот — нема начин да пренесете ID на друг работен простор и да гледате туѓи податоци.
• Отповикајте клуч во секое време од /api-keys; отповикувањето важи веднаш.
• Третирајте го API-клучот како лозинка. Ако случајно го зачувате во јавно складиште за код, веднаш отповикајте го и создајте нов.