I-API yomphakathi & okhiye be-API

1. Ukubuka konke

I-API ye-MousePlayer ikuvumela ukhiphe idatha endaweni yakho yokusebenzela uye kumadeshibhodi akho, enqolobaneni yedatha noma kumathuluzi angaphakathi. Ngaphandle kokunamathisela ama-ID amakhasimende kumaseshini (identify, kudinga ukhiye onobubanzi bokubhala, bheka Ububanzi Bokhiye), ingeyokuthi kufundwe kuphela: ayikho idatha engashintshwa noma isuswe nge-API.

• I-URL eyisisekelo: https://www.mouseplayer.com/api/v1/
• Zonke izimpendulo ziyi-JSON.
• Zonke izicelo ziqinisekiswa ngokhiye we-API futhi zikhawulelwa ngokuzenzakalela endaweni yokusebenzela lowo khiye ongowayo — ukhiye wendawo yokusebenzela eyodwa awukwazi neze ukubona idatha yenye, ngisho nangephutha.
• Okurekhodiwe okuphelele kokudlala kabusha kweseshini (ukunyakaza kwegundane, izithombe ze-DOM) akuvezwa nge-API. Uthola imethadatha yeseshini, ukubukwa kwamakhasi, izehlakalo zangokwezifiso nezingxenye — kwanele ukwakha imibiko namadeshibhodi ngaphandle kokuhambisa umthwalo wedatha wokudlala kabusha oluhlaza.

2. Ukuqinisekisa

Dala futhi uphathe okhiye bakho be-API ngaphansi kokuthi Okhiye Be-API kumenyu ye-akhawunti yakho (/api-keys). Abanikazi nabaphathi bendawo yokusebenzela kuphela abangadala noma bahoxise okhiye.

Thumela ukhiye njengethokheni ye-Bearer esihlokweni esithi Authorization sazo zonke izicelo:

Okhiye abangekho, abakheke kabi noma abahoxisiwe bathola impendulo ethi 401 :

Uhlelo oludingekayo

I-REST API iyingxenye yezinhlelo ze- Business ne- Enterprise . Uhlelo luthathwa kumnikazi wendawo yokusebenzela, ngakho amalungu eqembu amenyiwe ayaluzuza. Ukuhlola kwenzeka kuzo zonke izicelo, hhayi kuphela lapho kudalwa ukhiye — uma indawo yokusebenzela yehliselwa ohlelweni oluphansi, okhiye abakhona bayayeka ukusebenza babuyise 403.

Ububanzi bokhiye

Wonke ukhiye uqukethe ububanzi bawo esiqalweni sawo, ukuze ubone ukuthi wenzani ngokuwubuka nje — ku- .env, ethikithini, kutheminali.

3. Imikhawulo yezinga

Ukhiye ngamunye we-API ukhawulelwe ezicelweni ezingu-60 ngomzuzu, zibalwa efasiteleni lesikhathi elihambayo. Uma wedlula lokho, izicelo zithola impendulo ethi 429 kuze kuphele iwindi lesikhathi:

4. Iziphetho

GET/api/v1/projects

Ibala zonke iziphrojekthi (amasayithi alandelelwayo) endaweni yakho yokusebenzela.

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

Ibala amaseshini ezivakashi arekhodelwe iphrojekthi, amasha kuqala. Ihlukaniswe ngamakhasi.

GET/api/v1/sessions/{session_id}

Imethadatha yeseshini eyodwa, kanye nokubukwa kwamakhasi kwayo. Ikhetha ukungafaki umthwalo wedatha wokudlala kabusha ophelele — sebenzisa isidlali sedeshibhodi kulokho.

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

Izehlakalo zangokwezifiso ezenzeke phakathi neseshini (zona lezo ozithumela nge- mp('event', ...)), kuhlanganise namapharamitha azo.

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

Ibala izingxenye zezivakashi ezichazwe kuphrojekthi (zombili izingxenye zephrojekthi nezahlukaniswa kuyo yonke indawo yokusebenzela).

5. Ukunamathisela i-ID yekhasimende engxenyeni yakho yeseva

Isiphequluli sivame ukungazi ukuthi ubani ohlezi lapho. Kumkhiqizo we-B2B ubunikazi buqinisekiswa ngemva kokungena — engxenyeni yakho yeseva. Esitolo buqinisekiswa ngokuvuma i-oda. Lesi siphetho singaleso sikhathi ngqo.

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

I-ID ibe isivela ohlwini lwamaseshini, iyasesheka lapho, futhi i-webhook ethi session_identified iyasebenza — okuyindlela efika ngayo ku-CRM yakho.

6. Ama-webhook: ukuqinisekisa isiginesha

Ama-webhook asethwa ngephrojekthi ngaphansi kokuthi Ukuhlanganisa, lapho uthola nemfihlo yokusayina. Konke ukuthunyelwa kuqukethe lezi zihloko:

Isiginesha iyi-HMAC-SHA256 yombhalo othi timestamp + "." + raw body, kusetshenziswa imfihlo yokusayina yephrojekthi yakho njengokhiye.

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

Ukuthumela nokuphinda kuzanywe

Ukuthumela okwehlulekile kuphindwa ngemva kuka- 1 min, 5 min, 15 min, 1 h no-6 h, bese kuyekwa. 4xx izimpendulo ngaphandle kwe- 408 ne- 429 aziphinde zizanywe — zithi "hhayi ngale ndlela", hhayi "hhayi njengamanje". Phendula ngo- 2xx ngokushesha bese wenza umsebenzi kamuva; ukuthumela kuphelelwa isikhathi ngemva kwemizuzwana engu-10.

Izehlakalo ezitholakalayo

7. Amaphutha & amakhodi esimo

8. Amanothi okuphepha

• Okhiye bokufunda kuphela (mp_ro_) abakwazi ukushintsha lutho. Okhiye bokubhala (mp_rw_) banganamathisela ama-ID amakhasimende kuphela; awukho ukhiye ongasusa idatha noma uthekelise idatha yokudlala kabusha eluhlaza.
• Zonke izicelo zikhawulelwa ngokuzenzakalela endaweni yokusebenzela yokhiye uqobo — ayikho indlela yokudlulisa i-ID yendawo ehlukile ubone idatha yomunye umuntu.
• Hoxisa ukhiye noma nini kokuthi /api-keys; ukuhoxisa kusebenza ngokushesha.
• Phatha ukhiye wakho we-API njengephasiwedi. Uma uwufaka ngephutha kunqolobane yekhodi yomphakathi, wuhoxise ngokushesha udale omusha.