API pubblica & chiavi API
Accesso programmatico all’area di lavoro — lettura di progetti, sessioni, eventi personalizzati e segmenti e associazione di ID cliente alle sessioni — protetto da chiavi API limitate all’area.
1. Panoramica
L’API MousePlayer permette di estrarre dati dall’area di lavoro verso dashboard, data warehouse o strumenti interni. A parte l’associazione di ID cliente alle sessioni (identify, richiede una chiave con ambito di scrittura: vedere Ambiti delle chiavi), è di sola lettura: nessun dato può essere modificato o eliminato tramite API.
- URL di base:
https://www.mouseplayer.com/api/v1/ - Tutte le risposte sono JSON.
- Ogni richiesta è autenticata con una chiave API e limitata automaticamente alla relativa area di lavoro — una chiave di un’area non può mai vedere i dati di un’altra, nemmeno per errore.
- La registrazione completa della sessione (movimenti del mouse, istantanee DOM) non è esposta tramite API. Si ottengono metadati, visualizzazioni di pagina, eventi personalizzati e segmenti — sufficienti per report e dashboard senza trasferire i dati grezzi di riproduzione.
2. Autenticazione
Crei e gestisca le chiavi sotto Chiavi API nel menu dell’account (/api-keys). Solo proprietari e amministratori dell’area possono creare o revocare chiavi.
Mantenga segreta la chiave. Dà accesso in lettura a tutta l’area. La chiave completa è mostrata una sola volta dopo la creazione — la conservi in un gestore di password o archivio di segreti. Se la perde, la revochi e ne crei un’altra.
Invii la chiave come token Bearer nell’intestazione Authorization di ogni richiesta:
Chiavi mancanti, non valide o revocate ricevono una risposta 401 :
Piano richiesto
L’API REST fa parte dei piani Business ed Enterprise . Si applica il piano del proprietario dell’area, ereditato quindi anche dai membri invitati. Il controllo avviene a ogni richiesta, non solo alla creazione della chiave — passando a un piano inferiore, le chiavi esistenti smettono di funzionare e restituiscono 403.
Ambiti delle chiavi
Ogni chiave riporta l’ambito nel prefisso, per riconoscerne i permessi a colpo d’occhio — in un file .env, in un ticket o in un terminale.
| Prefisso | Significato |
|---|---|
mp_ro_ | Sola lettura. Legge progetti, sessioni, eventi e segmenti. Non modifica nulla. |
mp_rw_ | Lettura e scrittura. Tutto quanto sopra, più l’associazione di ID cliente tramite l’endpoint identify. |
403 con un messaggio che indica l’ambito della chiave e quello richiesto. Non si può modificare dopo — crei una nuova chiave e revochi la precedente.3. Limiti di richieste
Ogni chiave API è limitata a 60 richieste al minuto, su finestra mobile. Oltre il limite le richieste ricevono una risposta 429 finché la finestra non lo consente:
Serve un limite superiore? Contatti l’assistenza e descriva il caso d’uso.
4. Endpoint
GET/api/v1/projects
Elenca tutti i progetti (proprietà monitorate) nell’area di lavoro.
GET/api/v1/projects/{channelid}/sessions
Elenca le sessioni registrate per un progetto, dalla più recente. Con paginazione.
| Parametro query | Descrizione |
|---|---|
page | Numero di pagina, predefinito 1. |
per_page | Risultati per pagina, predefinito 25, massimo 100. |
since | Solo sessioni iniziate in questa data o dopo (YYYY-MM-DD). |
until | Solo sessioni iniziate in questa data o prima. |
GET/api/v1/sessions/{session_id}
Metadati di una sessione e relative visualizzazioni di pagina. Esclude volutamente i dati completi di riproduzione — per quelli usi il lettore nella dashboard.
GET/api/v1/sessions/{session_id}/events
Eventi personalizzati della sessione (gli stessi inviati con mp('event', ...)), inclusi i parametri.
GET/api/v1/projects/{channelid}/segments
Elenca i segmenti di visitatori definiti per un progetto, sia specifici sia comuni all’area.
5. Associare un ID cliente dal backend
Il browser spesso non sa chi ha davanti. In un prodotto B2B l’identità si stabilisce dopo l’accesso — nel backend. In un negozio, alla conferma dell’ordine. L’endpoint serve proprio per quel momento.
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}}L’ID appare nell’elenco sessioni, diventa ricercabile e il webhook session_identified si attiva — così raggiunge il CRM.
"changed": false e non viene inviato alcun webhook. Un ordine ripetuto non crea un secondo potenziale cliente.| Stato | Quando |
|---|---|
400 | Campo mancante, user_id oltre 128 caratteri o contenente caratteri di controllo. Rifiutiamo anziché troncare — un ID accorciato silenziosamente non corrisponde a nulla nel CRM, pur sembrando un successo. |
404 | La sessione non esiste oppure non appartiene alla sua area. La risposta è volutamente uguale in entrambi i casi. |
403 | Il piano dell’area non include l’API. |
6. Webhook: verificare la firma
I webhook si configurano per progetto sotto Integrazioni, dove si trova anche il segreto di firma. Ogni consegna include queste intestazioni:
| Intestazione | Significato |
|---|---|
X-MousePlayer-Event | Nome evento, ad es. session_identified |
X-MousePlayer-Timestamp | Secondi Unix — parte del testo firmato |
X-MousePlayer-Attempt | 1 al primo tentativo, superiore nei successivi |
X-MousePlayer-Signature | sha256=<hex> |
La firma è un HMAC-SHA256 calcolato su timestamp + "." + raw body, usando nell'HMAC il segreto di firma del progetto come chiave.
// 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');
Consegna e nuovi tentativi
Una consegna fallita viene ritentata dopo 1 min, 5 min, 15 min, 1 h e 6 h, poi abbandonata. Le risposte 4xx diverse da 408 e 429 non vengono mai ritentate — significano "non così", non "non ora". Risponda 2xx rapidamente e svolga il lavoro dopo; la consegna scade dopo 10 secondi.
Eventi disponibili
| Evento | Si attiva |
|---|---|
session_identified | Quando una sessione riceve il primo ID cliente — dal browser o dall’API |
session_ended | Una volta, alla chiusura della sessione |
goal_reached | Una volta per sessione, quando un evento personalizzato soddisfa un obiettivo. Solo obiettivi di tipo «event» — non vengono valutati obiettivi URL, durata, visualizzazioni o funnel. Include goal_id, goal_name, goal_value e currency. |
high_value_session | Quando un visitatore supera per la prima volta nell’arco di una giornata la soglia di valore del progetto. La soglia è derivata dalla distribuzione dei suoi punteggi (90° percentile degli ultimi 90 giorni), non un numero fisso, ed esiste solo dopo almeno 20 visitatori valutati. Include visitor_id, value_score, threshold e la sessione di quel giorno più adatta alla visione. |
funnel_dropoff | Al termine di una sessione entrata in un funnel senza completarlo. Indica il passaggio dove si è fermata (dropped_at). Un abbandono è l’assenza di un evento e si conosce solo alla fine della sessione. Le sessioni mai entrate nel funnel non sono abbandoni e non attivano l’evento. |
high_friction_session | Una volta per sessione, quando il punteggio di attrito raggiunge la soglia per la prima volta (60 su 100 per impostazione predefinita). Include friction_score, i segnali che lo compongono (reasons) e quello che ha fatto superare la soglia (trigger). |
element_broken | Una volta, quando un elemento monitorato non trova nulla in alcuna visualizzazione controllata per diversi giorni — di solito dopo un rilancio. Si riattiva solo dopo che il contrassegno ha trovato corrispondenze e si è interrotto di nuovo. Non appartiene a nessuna sessione: session_id e session_url sono null, link_url apre invece il contrassegno e subject_id identifica il contrassegno — uguale per ogni versione, così un nuovo selettore che fallisce di nuovo si unisce all’incidente aperto. Include rule_id, rule_name, selector, page, checked_page_views, window_days e last_matched. Nessun dato dei visitatori. |
element_recovered | Il rientro dell’allarme per element_broken: quando il contrassegno trova davvero un elemento — poche visualizzazioni non bastano. Inviato solo se element_broken è stato inviato via webhook; non ha un interruttore proprio: iscriversi a element_broken lo include. Stesso subject_id, affinché PagerDuty risolva l’incidente e Opsgenie chiuda l’avviso. Include anche matched_page_views e checked_page_views in aggiunta. |
anomaly_detected | Una volta al giorno, quando ieri differisce nettamente dai 28 giorni precedenti: molte meno o più sessioni, calo del tasso di obiettivi, più sessioni con attrito o errori JS. La stessa metrica e direzione restano silenziose per una settimana (regolabile). Non appartiene a nessuna sessione: session_id e session_url sono null, link_url apre la panoramica del progetto e subject_id identifica metrica, direzione e giorno. Include metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score e i campi leggibili summary e hint. Nessun dato dei visitatori. Per Web Vitals, measurements sostituisce sessions, e page (vuoto per l’intero sito) e device (desktop oppure mobil) indicano dove è successo; link_url apre quindi la scheda Web Vitals. |
rage_click | Al rilevamento di un clic di rabbia |
error_detected | A un’eccezione del browser |
ce | Iscrizione collettiva ai suoi eventi personalizzati. Questa non include gli eventi precedenti — hanno interruttori propri. |
7. Errori & codici di stato
| Stato | Significato |
|---|---|
200 | Successo. |
401 | Chiave API mancante, non valida o revocata. |
404 | Progetto o sessione inesistente o non appartenente all’area. |
429 | Limite superato — oltre 60 richieste al minuto con questa chiave. |
403 | Il piano dell’area non include l’API REST. Il messaggio indica piano richiesto e attuale. |
8. Note di sicurezza
- Le chiavi di sola lettura (mp_ro_) non modificano nulla. Quelle di scrittura (mp_rw_) possono solo associare ID cliente; nessuna chiave può cancellare dati o esportare dati grezzi di riproduzione.
- Ogni richiesta è limitata all’area della chiave — non si può passare l’ID di un’altra area per vederne i dati.
- Revochi una chiave in ogni momento da /api-keys; la revoca è immediata.
- Tratti la chiave API come una password. Se la inserisce per errore in un repository pubblico, la revochi subito e ne crei un’altra.
Pagine eventi limitate (API v1, 14/10/2026)
GET /api/v1/sessions/{session_id}/events restituisce fino a 100 eventi per impostazione predefinita. Imposti per_page su un intero da 1 a 100. Segua pagination.next_cursor inviando cursor invariato nella richiesta successiva; mantenga sessione e area. Gli eventi sono ordinati per created_at ed event_id. I cursori sono firmati e legati alla sessione e all’area. Non viene restituito un totale né un numero di pagina.
L’array data e la mappa params restano disponibili. pagination.returned indica il numero restituito; pagination.has_more la presenza di un’altra pagina. next_cursor è null al termine. Una risposta è limitata a 524288 byte, quindi una pagina può contenere meno eventi di per_page. Per evento vengono restituite al massimo 128 righe di parametri; params_truncated è true se ne esistono altre. I singoli parametri testuali mantengono il limite del database di 255 caratteri. I parametri troncati non sono disponibili da questo endpoint. Ridurre per_page non aumenta il limite dei parametri.
Dimensioni pagina non valide, cursori alterati o per altre sessioni o aree restituiscono 400. Dati troppo grandi di un singolo evento restituiscono 413. I controlli esistenti restituiscono ancora 401, 403, 404 o 409 secondo il caso.
Il limite resta di 60 richieste autenticate per chiave API al minuto. Il superamento restituisce 429 con Retry-After: 60. Se Redis o il limitatore non sono disponibili, le richieste restituiscono 503 con Retry-After: 5 e non sono mai ammesse senza limite. Rispetti Retry-After e aggiunga un’attesa casuale tra i tentativi, senza cicli serrati. Anche gli errori del database eventi restituiscono 503. I cursori non congelano un’istantanea: inserimenti simultanei con timestamp precedenti possono richiedere una nuova scansione.
GET /api/v1/sessions/s_example/events?per_page=25 GET /api/v1/sessions/s_example/events?per_page=25&cursor=SIGNED_CURSOR
/api/v1/native è una rotta di controllo backend riservata a Dev per l’anteprima dell’SDK nativo. Resta disattivata in produzione. Le chiavi Bearer backend richiedono ambito di lettura per list/replay e di scrittura per register/grant/delete/disable. Si applicano ulteriori controlli di disponibilità dell’anteprima nativa. Non incorpori mai chiavi API permanenti dell’area in un’app mobile.