Avalik API & API võtmed

1. Ülevaade

MousePlayeri API võimaldab tuua andmeid tööruumist teie enda töölaudadele, andmelattu või sisemistesse tööriistadesse. Peale kliendi-ID-de lisamise seanssidele (identify, vajab kirjutusõigusega võtit, vt võtmete õigusi) on see kirjutuskaitstud: API kaudu ei saa andmeid muuta ega kustutada.

• Baas-URL: https://www.mouseplayer.com/api/v1/
• Kõik vastused on JSON-vormingus.
• Iga päring autenditakse API võtmega ja piiratakse automaatselt tööruumiga, millele võti kuulub — ühe tööruumi võti ei saa kunagi näha teise tööruumi andmeid, isegi kogemata.
• Täielikku seansi taasesituse salvestist (hiireliigutusi, DOM-i hetktõmmiseid) ei avaldata API kaudu. Saate seansi metaandmed, lehevaatamised, kohandatud sündmused ja segmendid — piisavalt aruannete ja töölaudade loomiseks ilma taasesituse toorandmeid ringi saatmata.

2. Autentimine

Looge ja hallake API võtmeid oma konto menüü jaotises API võtmed (/api-keys). Võtmeid saavad luua ja tühistada ainult tööruumi omanikud ja administraatorid.

Saatke võti Bearer-pääsutõendina iga päringu päises Authorization:

Puuduva, vigase või tühistatud võtme korral tagastatakse vastus 401:

Nõutav pakett

REST API kuulub pakettidesse Business ja Enterprise. Arvesse läheb tööruumi omaniku pakett, seega pärivad selle ka kutsutud meeskonnaliikmed. Kontroll tehakse iga päringu korral, mitte ainult võtme loomisel — kui tööruum viiakse madalamasse paketti, lakkavad olemasolevad võtmed töötamast ja tagastavad vastuse 403.

Võtmete õigused

Iga võtme õigused kajastuvad selle prefiksis, mistõttu piisab võtmele pilguheitmisest — kas .env, pöördumise või terminali sees.

3. Päringusageduse piirangud

Iga API võtme piirang on 60 päringut minutis, arvestatuna libisevas ajaaknas. Piiri ületamisel saavad päringud vastuse 429 kuni ajaaken vabaneb:

4. Lõpp-punktid

GET/api/v1/projects

Loetleb kõik teie tööruumi projektid (jälgitavad ressursid).

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

Loetleb projekti salvestatud külastajaseansid, uusimad eespool. Toetab lehekülgedeks jaotamist.

GET/api/v1/sessions/{session_id}

Ühe seansi metaandmed koos lehevaatamistega. Täielikud taasesituse andmed on teadlikult välja jäetud — kasutage nende vaatamiseks töölaua mängijat.

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

Seansi jooksul käivitunud kohandatud sündmused (samad, mille saadate kutsega mp('event', ...)) koos nende parameetritega.

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

Loetleb projekti jaoks määratud külastajasegmendid (nii projektipõhised kui ka kogu tööruumi segmendid).

5. Kliendi-ID lisamine teie taustasüsteemist

Brauser ei tea sageli, kes seda kasutab. B2B-tootes selgub identiteet pärast sisselogimist — teie taustasüsteemis. Poes selgub see tellimuse kinnitamisel. See lõpp-punkt on mõeldud täpselt selleks hetkeks.

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 ilmub seejärel seansside loendisse, on seal otsitav ning käivitub session_identified veebihaak — nii jõuab see teie CRM-i.

6. Veebihaagid: allkirja kontrollimine

Veebihaagid seadistatakse iga projekti jaotises Integratsioonid, kust leiate ka allkirjastamissaladuse. Iga edastus sisaldab järgmisi päiseid:

Allkiri on HMAC-SHA256, mille sisend on timestamp + "." + raw body ja võti teie projekti allkirjastamissaladus.

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

Edastus ja korduskatsed

Ebaõnnestunud edastust proovitakse uuesti pärast 1 minutit, 5 minutit, 15 minutit, 1 tundi ja 6 tundi, seejärel loobutakse. 4xx vastuseid, välja arvatud 408 ja 429, ei proovita uuesti — need ütlevad "mitte sel viisil", mitte "mitte praegu". Vastake koodiga 2xx kiiresti ja tehke töö hiljem; edastus aegub 10 sekundi pärast.

Saadaolevad sündmused

7. Vead & olekukoodid

8. Turvamärkused

• Ainult lugemiseks mõeldud võtmed (mp_ro_) ei saa midagi muuta. Kirjutusõigusega võtmed (mp_rw_) saavad ainult kliendi-ID-sid lisada; ükski võti ei saa andmeid kustutada ega taasesituse toorandmeid eksportida.
• Iga päring piiratakse automaatselt võtme enda tööruumiga — teise tööruumi ID edastamisega pole võimalik kellegi teise andmeid näha.
• Võtme saate igal ajal tühistada lehel /api-keys; tühistamine jõustub kohe.
• Käsitlege API võtit nagu parooli. Kui lisate selle kogemata avalikku repositooriumi, tühistage see kohe ja looge uus.