Publiskais API & API atslēgas

1. Pārskats

MousePlayer API ļauj iegūt darbvietas datus saviem informācijas paneļiem, datu noliktavai vai iekšējiem rīkiem. Izņemot klientu ID piesaistīšanu sesijām (identify, vajadzīga atslēga ar rakstīšanas tvērumu, skatiet Atslēgu tvērumi), tas ir tikai lasāms: ar API nevar mainīt vai dzēst datus.

• Pamata URL: https://www.mouseplayer.com/api/v1/
• Visas atbildes ir JSON.
• Katrs pieprasījums tiek autentificēts ar API atslēgu un automātiski ierobežots ar darbvietu, kurai atslēga pieder, — vienas darbvietas atslēga nekad nevar redzēt citas darbvietas datus, pat nejauši.
• Pilnais sesijas atskaņojuma ieraksts (peles kustības, DOM momentuzņēmumi) API nav pieejams. Saņemat sesiju metadatus, lapu skatījumus, pielāgotus notikumus un segmentus — pietiekami pārskatiem un informācijas paneļiem bez neapstrādāto atskaņojuma datu pārsūtīšanas.

2. Autentifikācija

Izveidojiet un pārvaldiet API atslēgas sava konta izvēlnes sadaļā API atslēgas (/api-keys). Atslēgas izveidot vai atsaukt drīkst tikai darbvietas īpašnieki un administratori.

Sūtiet atslēgu kā Bearer žetonu katra pieprasījuma Authorization galvenē:

Trūkstošas, nepareizi veidotas vai atsauktas atslēgas saņem 401 atbildi:

Plāna prasība

REST API ir daļa no Business un Enterprise plāniem. Plāns tiek ņemts no darbvietas īpašnieka, tāpēc uzaicinātie komandas dalībnieki to pārmanto. Pārbaude notiek katrā pieprasījumā, ne tikai atslēgas izveides laikā, — ja darbvietas plāna līmenis tiek pazemināts, esošās atslēgas pārstāj darboties un atgriež 403.

Atslēgu tvērumi

Katras atslēgas tvērums ir tās prefiksā, lai pēc izskata vien varētu pateikt, ko tā dara, — .env, pieprasījumā vai terminālī.

3. Pieprasījumu biežuma ierobežojumi

Katrai API atslēgai ir ierobežojums: 60 pieprasījumi minūtē, kas uzskaitīti slīdošā laika logā. Pēc pārsniegšanas pieprasījumi saņem 429 atbildi, līdz logs atbrīvojas:

4. Galapunkti

GET/api/v1/projects

Uzskaita visus projektus (izsekotos objektus) jūsu darbvietā.

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

Uzskaita projektam ierakstītās apmeklētāju sesijas, vispirms jaunākās. Ar dalījumu lapās.

GET/api/v1/sessions/{session_id}

Vienas sesijas metadati un tās lapu skatījumi. Apzināti neiekļauj pilnos atskaņojuma datus — tiem izmantojiet informācijas paneļa atskaņotāju.

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

Sesijas laikā aktivizētie pielāgotie notikumi (tie paši, ko sūtāt ar mp('event', ...)), ieskaitot parametrus.

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

Uzskaita projektam definētos apmeklētāju segmentus (gan projekta, gan visas darbvietas segmentus).

5. Klienta ID piesaistīšana no aizmugursistēmas

Pārlūks bieži nezina, kas pie tā sēž. B2B produktā identitāte tiek noteikta pēc pieteikšanās — jūsu aizmugursistēmā. Veikalā tas notiek ar pasūtījuma apstiprinājumu. Šis galapunkts ir paredzēts tieši tam brīdim.

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

Pēc tam ID parādās sesiju sarakstā un ir tajā meklējams, un nostrādā session_identified tīmekļa aizķere — tā tas nonāk jūsu CRM.

6. Tīmekļa aizķeres: paraksta pārbaude

Tīmekļa aizķeres konfigurē katram projektam sadaļā Integrācijas, kur atrodams arī parakstīšanas noslēpums. Katra piegāde ietver šīs galvenes:

Paraksts ir HMAC-SHA256 vērtībai timestamp + "." + raw body ar jūsu projekta parakstīšanas noslēpumu kā atslēgu.

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

Piegāde un atkārtoti mēģinājumi

Neveiksmīga piegāde tiek atkārtota pēc 1 min, 5 min, 15 min, 1 h un 6 h, pēc tam mēģinājumi tiek pārtraukti. 4xx atbildes, izņemot 408 un 429, netiek atkārtotas — tās saka "ne šādi", nevis "ne tagad". Ātri atbildiet ar 2xx un darbu veiciet pēc tam; piegādes noildze ir 10 sekundes.

Pieejamie notikumi

7. Kļūdas & statusa kodi

8. Drošības piezīmes

• Tikai lasīšanas atslēgas (mp_ro_) neko nevar mainīt. Rakstīšanas atslēgas (mp_rw_) var tikai piesaistīt klientu ID; neviena atslēga nevar dzēst datus vai eksportēt neapstrādātus atskaņojuma datus.
• Katrs pieprasījums automātiski ir ierobežots ar atslēgas darbvietu — nav iespējas nodot citu darbvietas ID un redzēt svešus datus.
• Atsauciet atslēgu jebkurā brīdī no /api-keys; atsaukšana stājas spēkā uzreiz.
• Izturieties pret API atslēgu kā pret paroli. Ja nejauši to komitējat publiskā repozitorijā, nekavējoties atsauciet un izveidojiet jaunu.