I-API evulelekileyo & izitshixo ze-API

1. Isishwankathelo

I-API yeMousePlayer ikuvumela ukuba ukhuphe idatha kwindawo yakho yokusebenza iye kwiideshibhodi zakho, kwindawo yakho yokugcina idatha okanye kwizixhobo zangaphakathi. Ngaphandle kokuqhoboshela izichongi zabathengi kwiiseshoni (identify, ifuna isitshixo esinemvume yokubhala, jonga imida yezitshixo) yeyokufunda kuphela: akukho datha inokutshintshwa okanye icinywe nge-API.

• I-URL esisiseko: https://www.mouseplayer.com/api/v1/
• Zonke iimpendulo ziyiJSON.
• Isicelo ngasinye siqinisekiswa ngesitshixo se-API size sibekelwe umda ngokuzenzekelayo wendawo yokusebenza yeso sitshixo — isitshixo senye indawo yokusebenza asinakuze sibone idatha yenye, nokuba kungempazamo.
• Ukurekhodwa okupheleleyo kokudlala kwakhona iseshoni (ukushukuma kwemawusi, imifanekiso yeDOM) akufumaneki nge-API. Ufumana imethadatha yeseshoni, ukujongwa kwamaphepha, iziganeko ezenzelwe wena namaqela — okwaneleyo ukwenza iingxelo needeshibhodi ngaphandle kokuthumela umthwalo wokurekhoda ongahlelwanga kwiindawo ngeendawo.

2. Ukuqinisekisa ufikelelo

Yenza ulawule izitshixo zakho ze-API phantsi kwe Izitshixo ze-API kwimenyu yeakhawunti yakho (/api-keys). Kuphela ngabanini nabalawuli bendawo yokusebenza abanokwenza okanye barhoxise izitshixo.

Thumela isitshixo njengethokheni yeBearer kwisihloko esithi Authorization sesicelo ngasinye:

Izitshixo ezingekhoyo, ezingabhalwanga kakuhle okanye ezirhoxisiweyo zifumana impendulo ethi 401 :

Isicwangciso esifunekayo

I-REST API iyinxalenye yezicwangciso ze Business ne Enterprise . Isicwangciso sithathwa ku mnini wendawo yokusebenza, ngoko amalungu eqela amenyiweyo asizuza kuye. Uqinisekiso luqhutywa kwisicelo ngasinye, hayi kuphela xa kusenziwa isitshixo — ukuba indawo yokusebenza yehliselwa kwisicwangciso esisezantsi, izitshixo ezikhoyo ziyayeka ukusebenza zize zibuyise 403.

Imida yezitshixo

Isitshixo ngasinye sithwala umda waso kwisimaphambili saso, ukuze ubone oko sikwenzayo ngokusijonga nje — kwi .env, kwitikiti, kwitheminali.

3. Imida yezicelo

Isitshixo ngasinye se-API sinomda we zicelo eziyi-60 ngomzuzu, ezilandelwa kwifestile yexesha eqhubekayo. Xa uwugqithile, izicelo zifumana impendulo ethi 429 de kudlule elo xesha:

4. Iindawo zokuphela

GET/api/v1/projects

Idwelisa zonke iiprojekthi (iiwebhusayithi ezilandelwayo) kwindawo yakho yokusebenza.

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

Idwelisa iiseshoni zeendwendwe ezirekhodelwe iprojekthi, ezona zintsha kuqala. Yahlulwe yangamaphepha.

GET/api/v1/sessions/{session_id}

Imethadatha yeseshoni enye, kunye nokujongwa kwamaphepha ayo. Ngabom ayiquki umthwalo opheleleyo wokudlala kwakhona — sebenzisa isidlali sedeshibhodi kuloo nto.

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

Iziganeko ezenzelwe wena ezithunyelwe ngexesha leseshoni (kwaezo uzithumela nge mp('event', ...)), kuquka iiparamitha zazo.

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

Idwelisa amaqela eendwendwe achazelwe iprojekthi (amaqela ale projekthi kuphela nawasebenza kuyo yonke indawo yokusebenza).

5. Ukuqhoboshela isichongi somthengi kwinkqubo yakho engasemva

Isikhangeli sidla ngokungazi ukuba ngubani ohleli apho. Kwimveliso yeB2B isichongi simiselwa emva kokungena kwiakhawunti — kwinkqubo yakho engasemva. Kwivenkile simiselwa ngengqinisekiso yeodolo. Le ndawo yokuphela yeyaloo mzuzu kanye.

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

Isichongi sivela kuluhlu lweeseshoni, siyakhangeleka apho, kwaye iwebhook ethi session_identified iyathunyelwa — yindlela esifikelela ngayo kwiCRM yakho.

6. Iiwebhook: ukuqinisekisa utyikityo

Iiwebhook zisetwa ngokweprojekthi phantsi kwe Uqhagamshelo, apho ufumana khona nemfihlo yokusayina. Ukuhanjiswa ngakunye kuthwala ezi zihloko:

Utyikityo yiHMAC-SHA256 phezu kwe timestamp + "." + raw body, isebenzisa imfihlo yokusayina yeprojekthi yakho njengesitshixo.

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

Ukuhanjiswa nokuzama kwakhona

Ukuhanjiswa okusileleyo kuphinda kuzanywe emva kwe mizuzu eyi-1, imizuzu eyi-5, imizuzu eyi-15, iyure e-1 neeyure eziyi-6, kuze kuyekwe. 4xx Iimpendulo 408 ngaphandle kwe 429 ne aziphindi zizanywe — zithi "hayi ngolu hlobo", hayi "hayi ngoku". Phendula ngo 2xx ngokukhawuleza uze wenze umsebenzi emva koko; ukuhanjiswa kuphelelwa lixesha emva kwemizuzwana eyi-10.

Iziganeko ezifumanekayo

7. Iimpazamo & iikhowudi zemeko

8. Amanqaku okhuseleko

• Izitshixo zokufunda kuphela (mp_ro_) azinakutshintsha nto. Izitshixo zokubhala (mp_rw_) zinokuqhoboshela izichongi zabathengi kuphela; akukho sitshixo sinokucima idatha okanye sikhuphele idatha yokudlala kwakhona engahlelwanga.
• Isicelo ngasinye sibekelwa umda ngokuzenzekelayo wendawo yokusebenza yesitshixo — akukho ndlela yokudlulisa isichongi sendawo yokusebenza eyahlukileyo uze ubone idatha yomnye umntu.
• Rhoxisa isitshixo nanini na ku /api-keys; ukurhoxisa kusebenza ngoko nangoko.
• Phatha isitshixo sakho se-API njengegama lokugqitha. Ukuba usifaka ngempazamo kwindawo evulelekileyo yokugcina ikhowudi, sirhoxise ngoko nangoko uze wenze esitsha.