API pubblika & ċwievet API

Aċċess programmatiku — aqraw proġetti, sessjonijiet, avvenimenti u segmenti, u żidu IDs tal-klijenti — protett b’ċwievet limitati għall-ispazju.

1. Ħarsa ġenerali

Ġibu data fid-dashboards, warehouse jew għodod tagħkom. Barra identify biex iżżidu IDs (jeħtieġ write scope, ara taħt), l-API hija għall-qari biss: ma tistgħux tbiddlu jew tħassru data.

  • URL bażi: https://www.mouseplayer.com/api/v1/
  • Tweġibiet JSON kollha.
  • Kull talba b’ċavetta API u limitata għall-ispazju tagħha — qatt data ta’ spazju ieħor, lanqas bi żball.
  • Ir-reġistrazzjoni sħiħa (maws, DOM snapshots) mhux disponibbli. Metadata, dehriet, avvenimenti u segmenti — biżżejjed għal rapporti mingħajr payloads mhux ipproċessati.

2. Awtentikazzjoni

Oħolqu u ġestixxu taħt Ċwievet API fil-menu tal-kont (/api-keys). Sidien u admins biss joħolqu jew jirrevokaw.

Żommu ċ-ċavetta sigrieta. Taqra kollox fl-ispazju. Tidher sħiħa darba — żommu f’password manager jew secrets vault. Mitlufa: irrevokaw u oħolqu oħra.

Ibgħtu Bearer token fil-header Authorization ta’ kull talba:

# List projects in your workspace curl -H "Authorization: Bearer mp_live_..." \ https://www.mouseplayer.com/api/v1/projects

Ċavetta nieqsa, ħażina jew revokata tirċievi 401 :

{ "error": "Invalid or missing API key. Use: Authorization: Bearer <key>" }

Rekwiżit tal-pjan

REST API fil-pjani Business u Enterprise . Il-pjan mill- sid tal-ispazju, għalhekk membri mistiedna jirtuh. Verifika fuq kull talba, mhux fil-ħolqien biss — downgrade jwaqqaf ċwievet eżistenti b’ 403.

Ambiti taċ-ċwievet

Prefiss juri l-ambitu — f’ .env, ticket jew terminal.

PrefissTifsira
mp_ro_Qari biss. Proġetti, sessjonijiet, avvenimenti u segmenti. Ebda bidla.
mp_rw_Qari u kitba. Kollha fuq u IDs permezz ta’ identify.
Agħżlu fil-ħolqien; standard qari biss. Read-only fuq kitba jagħti 403 b’messaġġ tal-ambitu u r-rekwiżit. Ma jinbidilx wara — ċavetta ġdida u revoka tal-qadima.

3. Limiti tat-talbiet

Kull ċavetta sa 60 talba kull minuta f’tieqa kontinwa. Wara tirċievi 429 sakemm tgħaddi t-tieqa:

{ "error": "Rate limit exceeded. Max 60 requests per minute." }

Għandkom bżonn aktar? Ikkuntattjaw l- Appoġġ bil-każ tagħkom.

4. Endpoints

GET/api/v1/projects

Il-proġetti kollha tal-ispazju.

{ "data": [ { "channelid": "955a45df5ee842cb", "domain": "yourdomain.com", "status": "active", "total_traffic_bytes": 27304765, "created_at": "2026-07-19 22:06:39", "last_used": "2026-08-05 01:12:55" } ] }

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

Sessjonijiet tal-proġett, ġodda l-ewwel. Paġinati.

ParametruDeskrizzjoni
pageNumru tal-paġna, standard 1.
per_pageRiżultati kull paġna, standard 25, massimu 100.
sinceSessjonijiet li jibdew minn din id-data (YYYY-MM-DD).
untilSessjonijiet li jibdew sa din id-data.
{ "data": [ { "session_id": "s_kfmist058_1785795295504", "visitor_id": "v_sv90jdpzo_1785795296042", "custom_user_id": null, "country": "DE", "device_type": "desktop", "is_bot": 0, "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105 } ], "pagination": { "page": 1, "per_page": 25, "total": 142, "total_pages": 6 } }

GET/api/v1/sessions/{session_id}

Metadata u dehriet għal sessjoni. Payload sħiħ apposta eskluż — għalih il-player.

{ "data": { "session_id": "s_kfmist058_1785795295504", "channelid": "955a45df5ee842cb", "visitor_id": "v_sv90jdpzo_1785795296042", "country": "DE", "asn_org": "Deutsche Telekom AG", "referrer": "https://duckduckgo.com/", "device_type": "desktop", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105, "pageviews": [ { "pageview_id": 1199, "url": "https://yourdomain.com/pricing", "page_title": "Pricing", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41" } ] } }

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

Avvenimenti tas-sessjoni (mibgħuta b’ mp('event', ...)), bil-parametri.

{ "data": [ { "event_id": 61, "pageview_id": 1199, "event_name": "add_to_cart", "created_at": "2026-08-04 00:14:59", "params": { "item_id": "SKU_98765", "price": 299.99 } } ] }

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

Segmenti definiti għall-proġett u għall-ispazju kollu.

{ "data": [ { "segment_id": 4, "name": "High Intent Visitors", "description": "Pageviews > 5", "badge_color": "cyan", "is_global": 0, "created_at": "2026-08-03 00:00:43" } ] }

5. ID tal-klijent mill-backend

Browser spiss ma jafx min hemm. B2B jidentifika wara login fil-backend — ħanut mal-konferma tal-ordni. Għal dak il-mument.

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 tidher u tinstab fil-lista, u l-webhook session_identified jaħdem — biex jasal fis-CRM.

Darbtejn bl-istess ID sigur. Tweġiba b’ "changed": false u ebda webhook. Ordni ripetuta ma toħloqx lead ieħor.
StatusMeta
400Qasam nieqes, user_id aktar minn 128 karattru jew control characters. Niċħdu mhux naqtgħu — ID mqassar ma jaqbel imkien iżda jidher suċċess.
404Sessjoni mhux eżistenti jew mhux fl-ispazju tagħkom. L-istess tweġiba apposta.
403Pjan bla API.

6. Webhooks: verifika tas-signature

Taħt Integrazzjonijiet għal kull proġett, flimkien mas-signing secret. Headers:

HeaderTifsira
X-MousePlayer-EventIsem l-avveniment, eż. session_identified
X-MousePlayer-TimestampUnix sekondi — parti mit-test iffirmat
X-MousePlayer-Attempt1 fl-ewwel tentattiv, ogħla fuq retries
X-MousePlayer-Signaturesha256=<hex>

HMAC-SHA256 fuq timestamp + "." + raw body, bis-signing secret tal-proġett bħala ċavetta.

// 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');
Iffirmaw il-body oriġinali qabel JSON parsing. Reserializing ibiddel ordni u spazji, signature qatt ma taqbel. Irrifjutaw timestamps eqdem minn ftit minuti — għalhekk hemm il-ħin.

Kunsinna u retries

Falliment jerġa’ jipprova wara 1 min, 5 min, 15 min, 1 h u 6 h, imbagħad jieqaf. 4xx Tweġibiet minbarra 408 u 429 ma jerġgħux jiġu ppruvati — ifissru "mhux hekk", mhux "mhux issa". Wieġbu 2xx malajr u aħdmu wara; timeout wara 10 sekondi.

Avvenimenti disponibbli

AvvenimentMeta
session_identifiedL-ewwel ID tal-klijent — browser jew API
session_endedDarba meta tagħlaq sessjoni
goal_reachedDarba kull sessjoni meta avveniment jilħaq għan. Għanijiet tat-tip "event" biss — URL, tul, dehriet u lembut mhux evalwati. Iġorr goal_id, goal_name, goal_value u currency.
high_value_sessionL-ewwel qabża tal-limitu tal-valur tal-proġett f’jum. Il-limitu mid-distribuzzjoni tal-punteġġi tagħkom (90 perċentil tal-aħħar 90 jum), mhux fiss, u jeħtieġ 20 viżitatur b’punteġġ. Iġorr visitor_id, value_score, threshold u l-aktar sessjoni li tiswa taraw tal-jum.
funnel_dropoffFi tmiem sessjoni li daħlet fil-lembut mhux lest. Isemmi l-pass (dropped_at). Tluq nuqqas ta’ avveniment, magħruf biss fl-aħħar. Sessjonijiet li ma daħlux mhumiex tluq u ma jattivawx.
high_friction_sessionDarba kull sessjoni mal-ewwel limitu tal-frizzjoni (standard 60 minn 100). Iġorr friction_score, sinjali (reasons) u dak li qabeż il-limitu (trigger).
element_brokenDarba meta element ma jsib xejn għal diversi jiem — spiss wara relaunch. Jerġa’ biss wara taqbil u ksur ġdid. Dan ta’ ebda sessjoni: session_id u session_url huma null, link_url jiftaħ il-marka, u subject_id isemmiha — l-istess bejn verżjonijiet biex selettur ġdid miksur jidħol fl-inċident miftuħ. Iġorr rule_id, rule_name, selector, page, checked_page_views, window_days u last_matched. Bla data tal-viżitaturi.
element_recoveredIs-sinjal ta’ rkupru għal element_broken: meta jsib element tassew — ftit dehriet mhux biżżejjed. Jintbagħat biss jekk element_broken ntbagħat bil-webhook, u bla swiċċ tiegħu: abbonament għal element_broken jinkludih. L-istess subject_id, għalhekk PagerDuty isolvi u Opsgenie jagħlaq. Iżid matched_page_views u checked_page_views .
anomaly_detectedDarba kuljum jekk ilbieraħ differenti mill-28 jum qabel: ħafna inqas jew aktar sessjonijiet, rata baxxa tal-għanijiet, aktar frizzjoni jew żbalji JS. L-istess metrika u direzzjoni siekta ġimgħa (aġġustabbli). Ta’ ebda sessjoni: session_id u session_url huma null, link_url jiftaħ il-ħarsa ġenerali, u subject_id isemmi metrika, direzzjoni u jum. Iġorr metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score u test leġġibbli summary u hint. Bla data tal-viżitaturi. Għal Web Vitals, measurements minflok sessions, u page (vojt għas-sit kollu) u device (desktop jew mobil) juru fejn; link_url jiftaħ it-tab Web Vitals.
rage_clickFuq klikk ta’ rabja
error_detectedFuq eċċezzjoni front-end
ceAbbonament kollettiv għall-avvenimenti tagħkom. Dan ma jinkludix dawk ta’ fuq — għandhom swiċċijiet separati.

7. Żbalji & status codes

StatusTifsira
200Suċċess.
401Ċavetta API nieqsa, ħażina jew revokata.
404Proġett jew sessjoni mhux eżistenti jew mhux tal-ispazju.
429Limitu maqbuż — aktar minn 60 talba/minuta b’din iċ-ċavetta.
403Pjan bla REST API. Messaġġ isemmi l-pjan meħtieġ u l-attwali.

8. Sigurtà

  • Ċwievet mp_ro_ ma jbiddlu xejn. mp_rw_ iżidu IDs biss; ebda ċavetta tħassar jew tesporta reġistrazzjonijiet mhux ipproċessati.
  • Talbiet limitati għall-ispazju taċ-ċavetta — ebda workspace ID differenti biex taraw data oħra.
  • Irrevokaw minn /api-keys f’kull ħin; immedjat.
  • Bħal password. Jekk tikkummittjawha f’repożitorju pubbliku, irrevokaw minnufih u oħolqu oħra.

Paġni tal-avvenimenti limitati (API v1, 14 Ottubru 2026)

GET /api/v1/sessions/{session_id}/events sa 100 avveniment awtomatikament. per_page numru sħiħ 1 sa 100. Segwu pagination.next_cursor b’cursor bla bidla fit-talba li jmiss; l-istess sessjoni u spazju. Ordni created_at u event_id. Cursors iffirmati u marbuta magħhom. Ebda total jew paġna numerika.

data array u params map jibqgħu. pagination.returned l-għadd reali; pagination.has_more paġna oħra. next_cursor null meta lest. Sa 524288 bytes, għalhekk inqas minn per_page possibbli. Sa 128 ringiela parametru kull avveniment; params_truncated true jekk aktar. Strings individwali sa 255 karattru. Parametri maqtugħa mhux disponibbli; per_page iżgħar ma jżidx il-limitu.

Daqs invalidu, cursor mibdul jew għal sessjoni/spazju ieħor: 400. Data individwali kbira wisq: 413. Verifiki tal-aċċess għadhom 401, 403, 404 jew 409 skont il-każ.

60 talba awtentikata kull ċavetta kull minuta. Eżawriment: 429 b’Retry-After: 60. Redis jew limiter mhux disponibbli: 503 b’Retry-After: 5, qatt bla limitu. Irrispettaw Retry-After u backoff każwali; ebda loop strett. Database failures 503 ukoll. Cursors mhux snapshot fiss: inserts b’ħinijiet qodma jistgħu jeħtieġu scan ġdid.

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 triq backend Dev biss għall-preview nattiv, mitfija fil-produzzjoni. Bearer keys read scope għal list/replay u write għal register/grant/delete/disable. Verifiki addizzjonali tal-preview japplikaw. Qatt ċwievet permanenti tal-ispazju f’app mobbli.