Offentlig API & API-nøkler

1. Oversikt

Med MousePlayer-API-et kan du hente data fra arbeidsområdet til egne dashbord, datavarehus eller interne verktøy. Bortsett fra å knytte kunde-ID-er til økter (identify, krever en nøkkel med skrivetilgang, se Nøkkelomfang) er det skrivebeskyttet: ingen data kan endres eller slettes via API-et.

• Basis-URL: https://www.mouseplayer.com/api/v1/
• Alle svar er JSON.
• Hver forespørsel autentiseres med en API-nøkkel og avgrenses automatisk til arbeidsområdet nøkkelen tilhører — en nøkkel fra ett arbeidsområde kan aldri se data fra et annet, heller ikke ved et uhell.
• Hele øktavspillingsopptaket (musebevegelser, DOM-øyeblikkskopier) er ikke tilgjengelig via API-et. Du får øktmetadata, sidevisninger, egendefinerte hendelser og segmenter — nok til å bygge rapporter og dashbord uten å flytte rundt på rå avspillingsdata.

2. Autentisering

Opprett og administrer API-nøklene under API-nøkler i kontomenyen (/api-keys). Bare arbeidsområdets eiere og administratorer kan opprette eller tilbakekalle nøkler.

Send nøkkelen som et Bearer-token i Authorization-headeren i hver forespørsel:

Manglende, feilformede eller tilbakekalte nøkler gir svaret 401:

Abonnementskrav

REST-API-et inngår i abonnementene Business og Enterprise. Abonnementet hentes fra arbeidsområdets eier, slik at inviterte teammedlemmer arver det. Kontrollen kjøres ved hver forespørsel, ikke bare når en nøkkel opprettes — nedgraderes et arbeidsområde, slutter eksisterende nøkler å virke og returnerer 403.

Nøkkelomfang

Hver nøkkel viser omfanget i sitt eget prefiks, så du kan se hva en nøkkel gjør bare ved å se på den — i en .env, i en sak, i en terminal.

3. Frekvensgrenser

Hver API-nøkkel er begrenset til 60 forespørsler per minutt, målt i et rullerende tidsvindu. Overskrider du det, får forespørslene svaret 429 til tidsvinduet er tømt:

4. Endepunkter

GET/api/v1/projects

Lister alle prosjekter (sporede nettsteder) i arbeidsområdet.

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

Lister besøksøkter tatt opp for et prosjekt, nyeste først. Sideinndelt.

GET/api/v1/sessions/{session_id}

Metadata for én økt og dens sidevisninger. Hele avspillingsnyttelasten er bevisst utelatt — bruk avspilleren i dashbordet til det.

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

Egendefinerte hendelser utløst under en økt (de samme hendelsene du sender med mp('event', ...)), inkludert parameterne.

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

Lister besøkssegmentene definert for et prosjekt (både prosjektspesifikke segmenter og segmenter for hele arbeidsområdet).

5. Knytt til en kunde-ID fra baksystemet

Nettleseren vet ofte ikke hvem som sitter der. I et B2B-produkt avklares identiteten etter innlogging — i baksystemet ditt. I en butikk avklares den med ordrebekreftelsen. Dette endepunktet er for akkurat det øyeblikket.

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-en vises deretter i øktlisten og kan søkes opp der, og webhooken session_identified utløses — slik når den CRM-et ditt.

6. Webhooks: kontroller signaturen

Webhooks konfigureres per prosjekt under Integrasjoner, der du også finner signeringshemmeligheten. Hver levering har disse headerne:

Signaturen er en HMAC-SHA256 over timestamp + "." + raw body, med prosjektets signeringshemmelighet som nøkkel.

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

Levering og nye forsøk

En mislykket levering forsøkes på nytt etter 1 min, 5 min, 15 min, 1 t og 6 t, deretter gis den opp. 4xx-svar bortsett fra 408 og 429 forsøkes ikke på nytt — de sier "ikke slik", ikke "ikke akkurat nå". Svar 2xx raskt og gjør arbeidet etterpå; leveringen får tidsavbrudd etter 10 sekunder.

Tilgjengelige hendelser

7. Feil & statuskoder

8. Sikkerhetsmerknader

• Lesenøkler (mp_ro_) kan ikke endre noe. Skrivenøkler (mp_rw_) kan bare knytte til kunde-ID-er; ingen nøkkel kan slette data eller eksportere rå avspillingsdata.
• Hver forespørsel avgrenses automatisk til nøkkelens eget arbeidsområde — det er ikke mulig å sende en annen arbeidsområde-ID og se andres data.
• Tilbakekall en nøkkel når som helst fra /api-keys; tilbakekallingen gjelder umiddelbart.
• Behandle API-nøkkelen som et passord. Hvis du ved et uhell committer en i et offentlig kodelager, tilbakekall den straks og opprett en ny.