Opinbert API & API-lyklar

1. Yfirlit

MousePlayer API gerir þér kleift að sækja gögn úr vinnusvæðinu í eigin stjórnborð, gagnavöruhús eða innri verkfæri. Fyrir utan tengingu viðskiptavinaauðkenna við lotur (identify, þarf lykil með skrifheimild, sjá Gildissvið lykla) er það aðeins til lestrar: ekki er hægt að breyta eða eyða gögnum með API.

• Grunnvefslóð: https://www.mouseplayer.com/api/v1/
• Öll svör eru JSON.
• Hver beiðni er auðkennd með API-lykli og sjálfkrafa afmörkuð við vinnusvæði hans — lykill eins vinnusvæðis getur aldrei séð gögn annars, ekki einu sinni fyrir slysni.
• Heildarendurspilun lotunnar (músarhreyfingar, DOM-skyndimyndir) er ekki aðgengileg í API. Þú færð lotulýsigögn, síðuskoðanir, sérsniðna atburði og hluta — nóg til að byggja skýrslur og stjórnborð án þess að flytja hráa endurspilunargagnahleðslu á milli.

2. Auðkenning

Búðu til og stjórnaðu API-lyklum undir API-lyklar í reikningsvalmyndinni (/api-keys). Aðeins eigendur og stjórnendur vinnusvæðis geta búið til eða afturkallað lykla.

Sendu lykilinn sem Bearer-tákn í hausnum Authorization í hverri beiðni:

Lyklar sem vantar, eru rangt sniðnir eða afturkallaðir fá svarið 401 :

Áskriftarkrafa

REST API er hluti af Business og Enterprise áskriftum. Áskriftin er tekin frá eiganda vinnusvæðisins svo boðnir teymismeðlimir njóta hennar. Athugunin keyrir í hverri beiðnien ekki aðeins við stofnun lykils — ef áskrift vinnusvæðis lækkar hætta núverandi lyklar að virka og skila 403.

Gildissvið lykla

Hver lykill ber gildissvið í eigin forskeyti svo sjá má hlutverk hans beint af honum — í .env, í verkbeiðni eða í skjáhermi.

3. Beiðnamörk

Hver API-lykill er takmarkaður við 60 beiðnir á mínútuí rúllandi tímaglugga. Þegar farið er yfir mörkin fá beiðnir svarið 429 þar til glugginn losnar:

4. Endapunktar

GET/api/v1/projects

Listar öll verkefni (rakin vefsvæði) á vinnusvæðinu.

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

Listar gestalotur skráðar fyrir verkefni, nýjast fyrst. Síðuskipt.

GET/api/v1/sessions/{session_id}

Lýsigögn einnar lotu ásamt síðuskoðunum hennar. Heildargagnahleðsla endurspilunar er vísvitandi undanskilin — notaðu spilarann í stjórnborðinu fyrir hana.

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

Sérsniðnir atburðir í lotu (sömu atburðir og þú sendir með mp('event', ...)), ásamt viðföngum þeirra.

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

Listar gestahluta skilgreinda fyrir verkefni (bæði verkefnisbundna og fyrir allt vinnusvæðið).

5. Tengja viðskiptavinaauðkenni úr bakendanum

Vafrinn veit oft ekki hver situr þar. Í B2B-vöru er auðkennið ákveðið eftir innskráningu — í bakendanum þínum. Í verslun við pöntunarstaðfestingu. Endapunkturinn er fyrir nákvæmlega þá stund.

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}}

Auðkennið birtist þá í lotulistanum og er leitanlegt þar og vefkrókurinn session_identified virkjast — þannig berst það í CRM-kerfið.

6. Vefkrókar: sannreyna undirskrift

Vefkrókar eru stilltir fyrir hvert verkefni undir Samþættingarþar sem þú finnur líka undirritunarleyndarmálið. Hver afhending ber þessa hausa:

Undirskriftin er HMAC-SHA256 af timestamp + "." + raw bodymeð undirritunarleyndarmáli verkefnisins sem lykli.

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

Afhending og endurtekningar

Misheppnuð afhending er endurtekin eftir 1 mín, 5 mín, 15 mín, 1 klst og 6 klstog síðan gefin upp. 4xx svör önnur en 408 og 429 eru ekki endurtekin — þau segja "ekki svona" en ekki "ekki núna". Svaraðu 2xx hratt og vinndu verkið eftir á; afhending rennur út eftir 10 sekúndur.

Tiltækir atburðir

7. Villur & stöðukóðar

8. Öryggisatriði

• Leslyklar (mp_ro_) geta engu breytt. Skriflyklar (mp_rw_) geta aðeins tengt viðskiptavinaauðkenni; enginn lykill getur eytt gögnum eða flutt út hrá endurspilunargögn.
• Hver beiðni er sjálfkrafa afmörkuð við eigið vinnusvæði lykilsins — engin leið er að senda annað vinnusvæðisauðkenni og sjá gögn annarra.
• Afturkallaðu lykil hvenær sem er frá /api-keys; afturköllun tekur strax gildi.
• Farðu með API-lykil eins og lykilorð. Ef þú setur hann óvart í opinbert kóðasafn skaltu afturkalla hann strax og búa til nýjan.