Viešoji API & API raktai

1. Apžvalga

MousePlayer API leidžia gauti darbo srities duomenis savo suvestinėms, duomenų sandėliui ar vidiniams įrankiams. Išskyrus klientų ID priskyrimą seansams (identify, reikia rašymo apimties rakto, žr. „Raktų apimtys“), ji skirta tik skaitymui: per API negalima keisti ar ištrinti jokių duomenų.

• Bazinis URL: https://www.mouseplayer.com/api/v1/
• Visi atsakymai pateikiami JSON formatu.
• Kiekviena užklausa autentifikuojama API raktu ir automatiškai apribojama darbo sritimi, kuriai jis priklauso — vienos darbo srities raktas niekada nemato kitos duomenų, net atsitiktinai.
• Visas seanso atkūrimo įrašas (pelės judesiai, DOM būsenos kopijos) nepateikiamas per API. Gaunate seanso metaduomenis, puslapių peržiūras, pasirinktinius įvykius ir segmentus — pakankamai ataskaitoms bei suvestinėms kurti neperduodant pirminių atkūrimo duomenų.

2. Autentifikavimas

Kurkite ir tvarkykite API raktus paskyros meniu skiltyje API raktai (/api-keys). Tik darbo srities savininkai ir administratoriai gali kurti ar atšaukti raktus.

Siųskite raktą kaip Bearer žetoną kiekvienos užklausos antraštėje Authorization:

Jei rakto trūksta, jis netinkamas ar atšauktas, gaunamas 401 atsakymas:

Paketo reikalavimas

REST API įtraukta į Business ir Enterprise paketus. Paketas nustatomas pagal darbo srities savininką, todėl pakviesti komandos nariai jį paveldi. Tikrinama kiekviena užklausa, ne tik rakto kūrimas — sumažinus darbo srities paketą esami raktai nustoja veikti ir grąžina 403.

Raktų apimtys

Kiekvieno rakto apimtis nurodyta jo prefikse, todėl iš karto matote, ką jis leidžia — faile .env, užklausoje ar terminale.

3. Užklausų dažnio ribos

Kiekvienam API raktui taikoma riba: 60 užklausų per minutę, skaičiuojant slenkančiu laikotarpiu. Viršijus užklausos gauna 429 atsakymą, kol laikotarpis atsilaisvina:

4. Galiniai adresai

GET/api/v1/projects

Pateikia visus jūsų darbo srities projektus (sekamus objektus).

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

Pateikia projekto lankytojų seansus, pirmiausia naujausius. Su puslapiavimu.

GET/api/v1/sessions/{session_id}

Vieno seanso metaduomenys ir jo puslapių peržiūros. Sąmoningai neįtraukiami visi atkūrimo duomenys — tam naudokite suvestinės leistuvę.

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

Seanso metu suaktyvinti pasirinktiniai įvykiai (tie patys, kuriuos siunčiate su mp('event', ...)) kartu su jų parametrais.

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

Pateikia projektui apibrėžtus lankytojų segmentus: konkretaus projekto ir visos darbo srities.

5. Kliento ID priskyrimas iš serverio

Naršyklė dažnai nežino, kas ja naudojasi. B2B produkte tapatybė nustatoma prisijungus — jūsų serveryje. Parduotuvėje – patvirtinus užsakymą. Šis galinis adresas skirtas būtent tam momentui.

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

Tada ID pasirodo seansų sąraše, jo galima ieškoti, o įvykis session_identified suaktyvina Webhook — taip jis pasiekia CRM.

6. Webhook: parašo tikrinimas

Webhook konfigūruojami kiekvienam projektui skiltyje Integracijos, kur taip pat rasite pasirašymo paslaptį. Kiekvienas siuntimas turi šias antraštes:

Parašas yra HMAC-SHA256, apskaičiuotas iš timestamp + "." + raw body, naudojant projekto pasirašymo paslaptį kaip raktą.

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

Pristatymas ir kartojimai

Nepavykęs siuntimas kartojamas po 1 min., 5 min., 15 min., 1 val. ir 6 val., vėliau bandymų atsisakoma. 4xx atsakymai, išskyrus 408 ir 429, yra nekartojami — jie reiškia "ne taip", o ne "ne dabar". Greitai atsakykite 2xx ir darbą atlikite vėliau; siuntimo skirtasis laikas – 10 sekundžių.

Galimi įvykiai

7. Klaidos & būsenos kodai

8. Saugumo pastabos

• Tik skaitymui skirti raktai (mp_ro_) nieko nekeičia. Rašymo raktai (mp_rw_) gali tik priskirti klientų ID; joks raktas negali ištrinti duomenų ar eksportuoti pirminių atkūrimo duomenų.
• Kiekviena užklausa automatiškai apribojama rakto darbo sritimi — negalima perduoti kitos darbo srities ID ir matyti svetimų duomenų.
• Bet kada atšaukite raktą skiltyje /api-keys; atšaukimas įsigalioja iš karto.
• API raktą saugokite kaip slaptažodį. Jei netyčia įtraukėte jį į viešą saugyklos commit, iš karto atšaukite ir sukurkite naują.