Offentligt API & API-nøgler

1. Oversigt

MousePlayer-API'et lader dig hente data fra dit arbejdsområde til egne dashboards, data warehouses eller interne værktøjer. Bortset fra tilknytning af kunde-ID'er til sessioner (identify, kræver en nøgle med skriveadgang, se Nøgleadgang) er det skrivebeskyttet: ingen data kan ændres eller slettes via API'et.

• Basis-URL: https://www.mouseplayer.com/api/v1/
• Alle svar er JSON.
• Hver forespørgsel godkendes med en API-nøgle og afgrænses automatisk til det arbejdsområde, nøglen tilhører — en nøgle fra ét arbejdsområde kan aldrig se et andets data, heller ikke ved et uheld.
• Den fulde sessionsoptagelse (musebevægelser, DOM-øjebliksbilleder) er ikke tilgængelig via API'et. Du får sessionsmetadata, sidevisninger, brugerdefinerede hændelser og segmenter — nok til rapporter og dashboards uden at flytte rå afspilningsdata rundt.

2. Godkendelse

Opret og administrer dine API-nøgler under API-nøgler i din kontomenu (/api-keys). Kun arbejdsområdets ejere og administratorer kan oprette eller tilbagekalde nøgler.

Send nøglen som et Bearer-token i Authorization-headeren på hver forespørgsel:

Manglende, forkert formaterede eller tilbagekaldte nøgler får et 401-svar:

Abonnementskrav

REST-API'et indgår i Business- og Enterprise-abonnementerne. Abonnementet bestemmes af arbejdsområdets ejer, så inviterede teammedlemmer arver det. Kontrollen udføres ved hver forespørgsel, ikke kun ved nøgleoprettelse — nedgraderes et arbejdsområde, holder eksisterende nøgler op med at virke og returnerer 403.

Nøgleadgang

Hver nøgles adgang fremgår af dens eget præfiks, så du kan se, hvad nøglen gør, blot ved at se på den — i en .env, i en sag eller i en terminal.

3. Forespørgselsgrænser

Hver API-nøgle er begrænset til 60 forespørgsler pr. minut, målt i et rullende tidsinterval. Overskrides grænsen, får forespørgsler et 429-svar, indtil intervallet er frigjort:

4. Endepunkter

GET/api/v1/projects

Viser alle projekter (sporede websteder) i dit arbejdsområde.

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

Viser besøgssessioner optaget for et projekt, nyeste først. Sideinddelt.

GET/api/v1/sessions/{session_id}

Metadata for én session samt dens sidevisninger. Udelader bevidst de fulde afspilningsdata — brug dashboardets afspiller til det.

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

Brugerdefinerede hændelser udløst under en session (de samme, du sender med mp('event', ...)), inklusive deres parametre.

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

Viser besøgssegmenter defineret for et projekt (både projektspecifikke segmenter og segmenter for hele arbejdsområdet).

5. Tilknyt et kunde-ID fra din backend

Browseren ved ofte ikke, hvem der sidder der. I et B2B-produkt fastlægges identiteten efter login — i din backend. I en butik sker det ved ordrebekræftelsen. Endepunktet er til netop det øjeblik.

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'et vises derefter på sessionslisten, kan søges frem der, og session_identified-webhooken udløses — sådan når det dit CRM.

6. Webhooks: Kontrollér signaturen

Webhooks konfigureres pr. projekt under Integrationer, hvor du også finder signeringshemmeligheden. Hver levering indeholder disse headere:

Signaturen er en HMAC-SHA256 af timestamp + "." + raw body, med projektets signeringshemmelighed som nøgle.

// 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 gentagne forsøg

En mislykket levering prøves igen efter 1 min., 5 min., 15 min., 1 t. og 6 t., hvorefter den opgives. 4xx-svar bortset fra 408 og 429 bliver ikke prøvet igen — de betyder "ikke sådan", ikke "ikke lige nu". Svar 2xx hurtigt, og udfør arbejdet bagefter; leveringen afbrydes efter 10 sekunder.

Tilgængelige hændelser

7. Fejl & statuskoder

8. Sikkerhedsbemærkninger

• Læsenøgler (mp_ro_) kan ikke ændre noget. Skrivenøgler (mp_rw_) kan kun tilknytte kunde-ID'er; ingen nøgle kan slette data eller eksportere rå afspilningsdata.
• Hver forespørgsel afgrænses automatisk til nøglens eget arbejdsområde — du kan ikke angive et andet arbejdsområdes ID og se andres data.
• Tilbagekald når som helst en nøgle fra /api-keys; tilbagekaldelsen træder straks i kraft.
• Behandl din API-nøgle som en adgangskode. Hvis du ved et uheld committer en til et offentligt repository, skal du straks tilbagekalde den og oprette en ny.