API publike & çelësat API

1. Përmbledhje

API-ja MousePlayer ju lejon të nxirrni të dhëna nga hapësira juaj e punës në panelet, depon e të dhënave ose mjetet tuaja të brendshme. Përveç bashkëngjitjes së ID-ve të klientëve në seanca (identify, kërkon çelës me fushëveprim shkrimi, shihni Fushëveprimet e çelësave), është vetëm për lexim: asnjë e dhënë nuk mund të ndryshohet ose fshihet përmes API-së.

• URL-ja bazë: https://www.mouseplayer.com/api/v1/
• Të gjitha përgjigjet janë JSON.
• Çdo kërkesë autentikohet me çelës API dhe kufizohet automatikisht në hapësirën e punës së cilës i përket çelësi — një çelës nga një hapësirë pune nuk mund të shohë kurrë të dhënat e një tjetre, as rastësisht.
• Regjistrimi i plotë i riprodhimit të seancës (lëvizje miu, pamje DOM të ruajtura) nuk ofrohet përmes API-së. Merrni metadata seancash, shikime faqesh, ngjarje të personalizuara dhe segmente — mjaft për të ndërtuar raporte dhe panele pa shpërndarë të dhënat e papërpunuara të riprodhimit.

2. Autentikimi

Krijoni dhe menaxhoni çelësat tuaj API te Çelësat API në menynë e llogarisë suaj (/api-keys). Vetëm pronarët dhe administratorët e hapësirës së punës mund të krijojnë ose revokojnë çelësa.

Dërgojeni çelësin si token Bearer në header-in Authorization të çdo kërkese:

Çelësat e munguar, të keqformuar ose të revokuar marrin një përgjigje 401 përkatëse:

Kërkesa e planit

REST API është pjesë e planeve Business dhe Enterprise për këtë shërbim. Plani merret nga pronari i hapësirës së punës, ndaj anëtarët e ftuar të ekipit e trashëgojnë. Kontrolli kryhet në çdo kërkesë, jo vetëm kur krijohet një çelës — nëse hapësira e punës kalon në nivel më të ulët, çelësat ekzistues ndalojnë së funksionuari dhe kthejnë 403.

Fushëveprimet e çelësave

Çdo çelës mbart fushëveprimin në prefiksin e vet, që ta kuptoni çfarë bën vetëm duke e parë — në një .env, në një kërkesë mbështetjeje, në një terminal.

3. Kufijtë e ritmit

Çdo çelës API kufizohet në 60 kërkesa në minutë, të ndjekura në një interval rrëshqitës. Pasi e tejkaloni, kërkesat marrin përgjigjen 429 derisa intervali të pastrohet:

4. Pika fundore

GET/api/v1/projects

Liston çdo projekt (pronë të ndjekur) në hapësirën tuaj të punës.

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

Liston seancat e vizitorëve të regjistruara për një projekt, më të rejat së pari. Me faqe.

GET/api/v1/sessions/{session_id}

Metadata për një seancë të vetme, plus shikimet e faqeve të saj. Qëllimisht përjashton të dhënat e plota të riprodhimit — për atë përdorni luajtësin e panelit.

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

Ngjarje të personalizuara të aktivizuara gjatë një seance (të njëjtat që dërgoni me mp('event', ...)), përfshirë parametrat e tyre.

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

Liston segmentet e vizitorëve të përcaktuara për një projekt (si segmentet specifike të projektit, ashtu edhe ato të gjithë hapësirës së punës).

5. Bashkëngjitja e ID-së së klientit nga serveri juaj

Shfletuesi shpesh nuk e di kush është aty. Në një produkt B2B identiteti përcaktohet pas hyrjes në llogari — në serverin tuaj. Në një dyqan përcaktohet me konfirmimin e porosisë. Kjo pikë fundore është pikërisht për atë çast.

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-ja pastaj shfaqet në listën e seancave, është e kërkueshme aty dhe webhook-u session_identified aktivizohet — kështu arrin te CRM-ja juaj.

6. Webhook-et: verifikimi i nënshkrimit

Webhook-et konfigurohen për çdo projekt te Integrimet, ku gjeni edhe sekretin e nënshkrimit. Çdo dërgesë mbart këto headers:

Nënshkrimi është HMAC-SHA256 mbi timestamp + "." + raw body, me sekretin e nënshkrimit të projektit tuaj si çelës.

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

Dërgimi dhe riprovimet

Një dërgesë e dështuar riprovohet pas 1 min, 5 min, 15 min, 1 h dhe 6 h, pastaj hiqet dorë. Përgjigjet 4xx që ndryshojnë nga 408 dhe 429 nuk riprovohen — ato thonë "jo kështu", jo "jo tani". Përgjigjuni 2xx shpejt dhe kryejeni punën më pas; dërgimi skadon pas 10 sekondash.

Ngjarje të disponueshme

7. Gabime & kode gjendjeje

8. Shënime sigurie

• Çelësat vetëm për lexim (mp_ro_) nuk mund të ndryshojnë gjë. Çelësat e shkrimit (mp_rw_) mund të bashkëngjitin vetëm ID klientësh; asnjë çelës nuk mund të fshijë të dhëna ose të eksportojë të dhëna të papërpunuara riprodhimi.
• Çdo kërkesë kufizohet automatikisht në hapësirën e punës së vetë çelësit — nuk ka mënyrë për të kaluar ID hapësire tjetër pune dhe për të parë të dhënat e dikujt tjetër.
• Revokojeni një çelës kurdoherë nga /api-keys; revokimi hyn në fuqi menjëherë.
• Trajtojeni çelësin API si fjalëkalim. Nëse e vendosni rastësisht në një depo publike me commit, revokojeni menjëherë dhe krijoni një të ri.