Julkinen API & API-avaimet

1. Yleiskuva

MousePlayerin API tuo työtilan tiedot omiin koontinäyttöihin, tietovarastoon tai sisäisiin työkaluihin. Asiakastunnusten liittämistä lukuun ottamatta (identify, vaatii kirjoitusoikeudellisen avaimen, katso Avainten oikeudet) se on vain lukuun: tietoja ei voi muokata tai poistaa API:n kautta.

• Perus-URL: https://www.mouseplayer.com/api/v1/
• Kaikki vastaukset ovat JSON-muodossa.
• Jokainen pyyntö todennetaan API-avaimella ja rajataan automaattisesti avaimen omaan työtilaan — yhden työtilan avain ei koskaan näe toisen tietoja edes vahingossa.
• Koko istuntotoistotallennetta (hiiren liikkeet, DOM-tilannekuvat) ei julkaista API:n kautta. Saat istunnon metatiedot, sivun katselut, mukautetut tapahtumat ja segmentit — riittävästi raportteihin ja koontinäyttöihin ilman raakojen toistotietojen siirtelyä.

2. Todennus

Luo ja hallitse API-avaimia tilivalikon kohdassa API-avaimet (/api-keys). Vain työtilan omistajat ja ylläpitäjät voivat luoda tai perua avaimia.

Lähetä avain Bearer-tunnuksena jokaisen pyynnön otsakkeessa Authorization:

Puuttuva, virheellinen tai peruttu avain saa vastauksen 401:

Tilausvaatimus

REST API sisältyy tilauksiin Business ja Enterprise. Tilaus tarkistetaan työtilan omistajalta, joten kutsutut tiimin jäsenet perivät sen. Tarkistus tehdään jokaisessa pyynnössä, ei vain avainta luotaessa — jos työtilan tilaus alennetaan, olemassa olevat avaimet lakkaavat toimimasta ja palauttavat 403.

Avainten oikeudet

Jokaisen avaimen oikeus näkyy sen omassa etuliitteessä. Avaimen toiminnan näkee siis katsomalla sitä — kohteessa .env, tukipyynnössä tai päätteessä.

3. Pyyntörajoitukset

Jokaisen API-avaimen raja on 60 pyyntöä minuutissa, liukuvassa aikaikkunassa. Ylityksen jälkeen pyynnöt saavat vastauksen 429, kunnes aikaikkunassa on taas tilaa:

4. Päätepisteet

GET/api/v1/projects

Luettelee työtilan kaikki projektit (seurattavat sivustot).

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

Luettelee projektin tallennetut kävijäistunnot uusimmasta alkaen. Sivutettu.

GET/api/v1/sessions/{session_id}

Yhden istunnon metatiedot ja sivun katselut. Koko toistosisältö on tarkoituksella jätetty pois — käytä siihen koontinäytön soitinta.

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

Istunnon aikana lauenneet mukautetut tapahtumat (samat, jotka lähetetään kutsulla mp('event', ...)), parametrit mukana.

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

Luettelee projektille määritetyt kävijäsegmentit (sekä projekti- että työtilakohtaiset).

5. Asiakastunnuksen liittäminen taustajärjestelmästä

Selain ei usein tiedä, kuka sitä käyttää. B2B-tuotteessa henkilöllisyys selviää kirjautumisen jälkeen — taustajärjestelmässä. Kaupassa se selviää tilausvahvistuksesta. Tämä päätepiste on juuri sitä hetkeä varten.

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

Tunnus näkyy sitten istuntoluettelossa ja on haettavissa. Samalla webhook session_identified laukeaa — ja näin tieto päätyy CRM:ään.

6. Webhookit: allekirjoituksen tarkistaminen

Webhookit määritetään projektikohtaisesti kohdassa Integraatiot, jossa on myös allekirjoitussalaisuus. Jokaisessa toimituksessa ovat seuraavat otsakkeet:

Allekirjoitus on HMAC-SHA256-tiiviste arvosta timestamp + "." + raw body, avaimena projektin allekirjoitussalaisuus.

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

Toimitus ja uusinnat

Epäonnistunutta toimitusta yritetään uudelleen aikojen 1 min, 5 min, 15 min, 1 h ja 6 h jälkeen, sitten luovutetaan. 4xx-vastauksia, lukuun ottamatta 408 ja 429, ei yritetä uudelleen — ne sanovat "ei näin", eivät "ei juuri nyt". Vastaa 2xx nopeasti ja tee työ sen jälkeen; toimitus aikakatkaistaan 10 sekunnissa.

Saatavilla olevat tapahtumat

7. Virheet & tilakoodit

8. Tietoturvahuomioita

• Vain lukuun tarkoitetut avaimet (mp_ro_) eivät voi muuttaa mitään. Kirjoitusavaimet (mp_rw_) voivat vain liittää asiakastunnuksia; mikään avain ei voi poistaa tietoja tai viedä raakoja toistotietoja.
• Jokainen pyyntö rajataan automaattisesti avaimen omaan työtilaan — toista työtilatunnusta ei voi antaa muiden tietojen katsomiseksi.
• Peru avain milloin tahansa kohdassa /api-keys; peruminen tulee voimaan heti.
• Käsittele API-avainta kuin salasanaa. Jos se päätyy vahingossa julkisen koodivaraston committiin, peru se heti ja luo uusi.