API publikoa & API gakoak

1. Ikuspegi orokorra

MousePlayer APIak zure lan-eremuko datuak zure aginte-paneletara, datu-biltegira edo barne-tresnetara ateratzen uzten dizu. Saioei bezero-IDak eransteaz gain (identify, idazteko esparruko gakoa behar du; ikus Gakoen esparruak), sarbidea irakurtzeko soilik da: ezin da daturik aldatu edo ezabatu APIaren bidez.

• Oinarrizko URLa: https://www.mouseplayer.com/api/v1/
• Erantzun guztiak JSON dira.
• Eskaera bakoitza API gakoarekin autentifikatzen da eta automatikoki mugatzen da gakoari dagokion lan-eremura — lan-eremu bateko gakoak ezin ditu inoiz beste lan-eremu baten datuak ikusi, ezta ustekabean ere.
• Saioaren erreprodukzio-grabazio osoa (saguaren mugimenduak, DOM kapturak) ez da APIaren bidez eskaintzen. Saioen metadatuak, orri-ikustaldiak, gertaera pertsonalizatuak eta segmentuak jasotzen dituzu — nahikoa txostenak eta aginte-panelak eraikitzeko, erreprodukzioaren karga gordina alde batetik bestera eraman gabe.

2. Autentifikazioa

Sortu eta kudeatu zure API gakoak hemen: API gakoak zure kontuaren menuan (/api-keys). Lan-eremuaren jabeek eta administratzaileek soilik sor edo baliogabetu ditzakete gakoak.

Bidali gakoa Bearer token gisa eskaera bakoitzaren Authorization goiburuan:

Falta diren, gaizki osatutako edo baliogabetutako gakoek honako hau jasotzen dute: 401 erantzuna:

Planaren eskakizuna

REST APIa bi mailatan sartzen da: Business eta Enterprise planetan. Plana lan-eremuaren jabearengandik hartzen da; beraz, gonbidatutako taldekideek heredatzen dute. Egiaztapena eskaera guztietan egiten da, ez gakoa sortzean soilik — lan-eremua maila txikiagora aldatzen bada, lehendik dauden gakoek funtzionatzeari uzten diote eta honako hau itzultzen dute: 403.

Gakoen esparruak

Gako bakoitzak bere esparrua aurrizkian darama; beraz, begiratuta bakarrik jakin dezakezu zer egiten duen — honako honetan: .env, eskaera batean edo terminal batean.

3. Eskaera-mugak

API gako bakoitzak honako muga du: 60 eskaera minutuko, leiho mugikor batean zenbatuta. Gainditzean, eskaerek honako hau jasotzen dute: 429 erantzuna, leihoa libratu arte:

4. Muturrak

GET/api/v1/projects

Zure lan-eremuko proiektu guztiak (jarraitutako propietateak) zerrendatzen ditu.

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

Proiektu baterako grabatutako bisitari-saioak zerrendatzen ditu, berrienak lehenik. Orrikatuta.

GET/api/v1/sessions/{session_id}

Saio bakar baten metadatuak eta haren orri-ikustaldiak. Erreprodukzioaren karga osoa nahita kanpoan uzten du — erabili aginte-paneleko erreproduzitzailea horretarako.

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

Saioan abiarazitako gertaera pertsonalizatuak (honako honekin bidaltzen dituzun gertaera berak: mp('event', ...)), beren parametroak barne.

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

Proiektu baterako definitutako bisitari-segmentuak zerrendatzen ditu, proiektuarenak nahiz lan-eremu osokoak.

5. Zure backend-etik bezero-IDa eranstea

Nabigatzaileak askotan ez daki nor dagoen bertan. B2B produktu batean identitatea saioa hasi ondoren zehazten da — zure backend-ean. Denda batean eskaeraren berrespenarekin zehazten da. Mutur hau une horretarako da hain zuzen.

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

IDa saio-zerrendan agertzen da orduan, han bila daiteke, eta session_identified webhooka abiarazten da — horrela iristen da zure CRMra.

6. Webhookak: sinadura egiaztatzea

Webhookak proiektuka konfiguratzen dira hemen: Integrazioak, eta sinadura-sekretua ere hor aurkituko duzu. Bidalketa bakoitzak goiburu hauek daramatza:

Sinadura HMAC-SHA256 bat da honako honen gainean: timestamp + "." + raw body, zure proiektuaren sinadura-sekretua gakotzat erabiliz.

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

Bidalketa eta berriz saiatzea

Huts egindako bidalketa berriro saiatzen da epe hauen ondoren: 1 min, 5 min, 15 min, 1 h eta 6 h, eta gero etsi egiten da. Honako kodeko 4xx erantzunak — honako hauek izan ezik: 408 eta 429 — ez dira berriro saiatzen — "ez horrela" diote, ez "ez orain". Erantzun 2xx azkar eta egin lana ondoren; bidalketak 10 segundoren buruan gainditzen du denbora-muga.

Gertaera erabilgarriak

7. Erroreak & egoera-kodeak

8. Segurtasun-oharrak

• Irakurtzeko soilik diren gakoek (mp_ro_) ezin dute ezer aldatu. Idazteko gakoek (mp_rw_) bezero-IDak soilik erants ditzakete; inolako gakok ezin ditu datuak ezabatu edo erreprodukzio-datu gordinak esportatu.
• Eskaera bakoitza automatikoki mugatzen da gakoaren lan-eremura — ez dago beste lan-eremu baten IDa pasatu eta beste norbaiten datuak ikusteko modurik.
• Baliogabetu gakoa edozein unetan hemen: /api-keys; baliogabetzeak berehala du eragina.
• Tratatu zure API gakoa pasahitza bezala. Ustekabean biltegi publiko batera igotzen baduzu, baliogabetu berehala eta sortu berria.