Javni API & API ključevi

1. Pregled

MousePlayer API omogućuje dohvat podataka iz radnog prostora u vlastite nadzorne ploče, skladište podataka ili interne alate. Osim pridruživanja ID-jeva kupaca sesijama (identify, potreban ključ s pravom pisanja, vidi Opsezi ključeva) služi samo za čitanje: podaci se putem API-ja ne mogu mijenjati ni brisati.

• Osnovni URL: https://www.mouseplayer.com/api/v1/
• Svi su odgovori JSON.
• Svaki se zahtjev autentificira API ključem i automatski ograničava na radni prostor kojem ključ pripada — ključ jednog radnog prostora nikad ne može vidjeti podatke drugog, čak ni slučajno.
• Cjelovita snimka reprodukcije sesije (pokreti miša, snimke stanja DOM-a) nije dostupna putem API-ja. Dobivate metapodatke sesije, prikaze stranica, prilagođene događaje i segmente — dovoljno za izvještaje i nadzorne ploče bez slanja neobrađenih podataka reprodukcije.

2. Autentifikacija

Izradite API ključeve i upravljajte njima pod API ključevi u izborniku računa (/api-keys). Samo vlasnici i administratori radnog prostora mogu izrađivati ili opozivati ključeve.

Pošaljite ključ kao Bearer token u zaglavlju Authorization svakog zahtjeva:

Za nedostajuće, neispravno oblikovane ili opozvane ključeve dobiva se odgovor 401:

Potreban plan

REST API dio je planova Business i Enterprise. Plan se preuzima od vlasnika radnog prostora pa ga pozvani članovi tima nasljeđuju. Provjera se izvršava pri svakom zahtjevu, a ne samo pri izradi ključa — ako radni prostor prijeđe na niži plan, postojeći ključevi prestaju raditi i vraćaju 403.

Opsezi ključeva

Svaki ključ nosi opseg u vlastitom prefiksu pa već pogledom možete reći što radi — u .env, u zadatku, u terminalu.

3. Ograničenja zahtjeva

Svaki API ključ ograničen je na 60 zahtjeva u minuti, uz praćenje u pomičnom vremenskom okviru. Nakon prekoračenja zahtjevi dobivaju odgovor 429 dok se okvir ne oslobodi:

4. Krajnje točke

GET/api/v1/projects

Navodi svaki projekt (praćeno web-mjesto) u radnom prostoru.

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

Navodi sesije posjetitelja snimljene za projekt, najnovije prvo. S podjelom na stranice.

GET/api/v1/sessions/{session_id}

Metapodaci pojedine sesije i njezini prikazi stranica. Namjerno ne uključuje cjelovite podatke reprodukcije — za to koristite reproduktor na nadzornoj ploči.

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

Prilagođeni događaji pokrenuti tijekom sesije (isti događaji koje šaljete s mp('event', ...)), uključujući parametre.

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

Navodi segmente posjetitelja definirane za projekt (i projektne i one za cijeli radni prostor).

5. Pridruživanje ID-ja kupca iz pozadinskog sustava

Preglednik često ne zna tko je pred njim. U B2B proizvodu identitet se utvrđuje nakon prijave — u vašem pozadinskom sustavu. U trgovini se utvrđuje potvrdom narudžbe. Ova krajnja točka služi upravo tom trenutku.

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 se zatim pojavljuje na popisu sesija, može se pretraživati i pokreće se webhook session_identified — tako stiže u vaš CRM.

6. Webhookovi: provjera potpisa

Webhookovi se postavljaju za svaki projekt pod Integracije, gdje se nalazi i tajna za potpisivanje. Svaka isporuka nosi ova zaglavlja:

Potpis je HMAC-SHA256 izračunat nad timestamp + "." + raw body, uz tajnu za potpisivanje projekta kao ključ.

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

Isporuka i ponovni pokušaji

Neuspjela isporuka ponavlja se nakon 1 min, 5 min, 15 min, 1 h i 6 h, zatim se odustaje. 4xx odgovori osim 408 i 429 se ne ponavljaju — znače "ne ovako", a ne "ne sada". Brzo odgovorite s 2xx i posao obavite poslije; isporuka istječe nakon 10 sekundi.

Dostupni događaji

7. Pogreške & statusni kodovi

8. Sigurnosne napomene

• Ključevi samo za čitanje (mp_ro_) ne mogu ništa mijenjati. Ključevi za pisanje (mp_rw_) mogu samo pridruživati ID-jeve kupaca; nijedan ključ ne može brisati podatke ni izvoziti neobrađene podatke reprodukcije.
• Svaki zahtjev automatski je ograničen na radni prostor ključa — ne postoji način da proslijedite ID drugog radnog prostora i vidite tuđe podatke.
• Opozovite ključ bilo kada na /api-keys; opoziv djeluje odmah.
• Postupajte s API ključem kao s lozinkom. Ako ga slučajno uključite u commit javnog repozitorija, odmah ga opozovite i izradite novi.