API ampahibemaso & lakile API

1. Topimaso

Ny API MousePlayer dia ahafahanao maka angona avy amin'ny sehatra fiasanao ho any amin'ny dashboard, trano fanatobiana angona na fitaovana anatiny anao. Ankoatra ny fampifandraisana ID mpanjifa amin'ny fotoam-pampiasana (identify, mila lakile misy sehatra fanoratana, jereo ny sehatra fahazoan-dalan'ny lakile), dia famakiana ihany izy: tsy misy angona azo ovaina na fafana amin'ny API.

• URL fototra: https://www.mouseplayer.com/api/v1/
• JSON avokoa ny valiny rehetra.
• Hamarinin'ny lakile API ny fangatahana tsirairay ary voafetra ho azy amin'ny sehatra fiasana ananan'ilay lakile — tsy afaka mahita ny angon'ny sehatra fiasana hafa mihitsy ny lakile avy amin'ny iray, na dia tsy fanahy iniana aza.
• Ny firaketana feno famerenana fotoam-pampiasana (fihetsiky ny totozy, sarin'ny DOM) dia tsy omena amin'ny API. Metadata momba ny fotoam-pampiasana, fijerena pejy, hetsika manokana sy sokajy no azonao — ampy hanaovana tatitra sy dashboard nefa tsy mampivezivezy ny angona manta ho an'ny famerenana.

2. Fanamarinana fidirana

Mamoròna sy tantano ny lakile API anao ao amin'ny Lakile API ao amin'ny menio kaontinao (/api-keys). Ny tompon'ny sehatra fiasana sy ny mpandrindra ihany no afaka mamorona na manafoana lakile.

Alefaso ho token Bearer ao amin'ny lohateny Authorization an'ny fangatahana tsirairay ilay lakile:

Mahazo valiny 401 ny lakile tsy hita, diso endrika na nofoanana:

Drafitra takiana

Anisan'ny drafitra Business sy Enterprise ny REST API. Avy amin'ny tompon'ny sehatra fiasana no alaina ilay drafitra, ka mandova izany ny mpikambana nasaina. Amin'ny fangatahana tsirairay no atao ny fanamarinana, fa tsy rehefa mamorona lakile ihany — raha ampidinina ny drafitry ny sehatra fiasana dia mijanona tsy miasa ny lakile efa misy ary mamerina 403.

Sehatra fahazoan-dalan'ny lakile

Mitondra ny sehatra fahazoan-dalany ao amin'ny tovony ny lakile tsirairay, ka fantatrao ny asany amin'ny fijerena azy fotsiny — ao amin'ny .env, ao amin'ny tapakila, ao amin'ny terminal.

3. Fetran'ny fangatahana

Voafetra amin'ny fangatahana 60 isa-minitra ny lakile API tsirairay, amin'ny varavarankelin'ny fotoana mihetsika. Raha mihoatra izany ianao dia mahazo valiny 429 ny fangatahana mandra-pahafahan'ilay varavarankely:

4. Teboka fiafarana

GET/api/v1/projects

Mitanisa ny tetikasa rehetra (fananana arahi-maso) ao amin'ny sehatra fiasanao.

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

Mitanisa ny fotoam-pampiasan'ny mpitsidika voarakitra ho an'ny tetikasa, ny vaovao indrindra aloha. Zaraina ho pejy.

GET/api/v1/sessions/{session_id}

Metadata ho an'ny fotoam-pampiasana iray, miampy ny fijerena pejiny. Fanahy iniana tsy ampidirina ny angona feno famerenana — ampiasao ny mpamaky ao amin'ny dashboard amin'izany.

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

Hetsika namboarina nitranga nandritra ny fotoam-pampiasana (ireo hetsika alefanao amin'ny mp('event', ...) ihany), miaraka amin'ny masontsivanany.

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

Mitanisa ireo sokajy mpitsidika voafaritra ho an'ny tetikasa (ireo natokana ho an'ny tetikasa sy ireo mihatra amin'ny sehatra fiasana manontolo).

5. Fampifandraisana ID mpanjifa avy amin'ny rafitra any aorianao

Matetika tsy fantatry ny mpitety hoe iza no eo. Amin'ny vokatra B2B dia aorian'ny fidirana no fantatra ny olona — any amin'ny rafitrao aoriana. Ao amin'ny fivarotana dia amin'ny fanamafisana kaomandy. Ho an'io fotoana io indrindra ity teboka ity.

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

Miseho ao amin'ny lisitry ny fotoam-pampiasana ilay ID avy eo, azo karohina ao, ary mandeha ny webhook session_identified — izay no fomba ahatongavany amin'ny CRM anao.

6. Webhook: fanamarinana ny sonia

Isaky ny tetikasa no ametrahana webhook ao amin'ny Tetezana, izay ahitana ny tsiambaratelo fanaovana sonia koa. Mitondra ireto lohateny ireto ny fanaterana rehetra:

HMAC-SHA256 amin'ny timestamp + "." + raw body ny sonia, mampiasa ny tsiambaratelo fanaovana sonian'ny tetikasanao ho lakile.

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

Fanaterana sy fanandramana indray

Andramana indray ny fanaterana tsy nahomby aorian'ny 1 min, 5 min, 15 min, 1 h ary 6 h, dia avela. 4xx Ny valiny 408 ankoatra ny 429 sy dia tsy andramana indray — milaza hoe "tsy amin'izao fomba izao" ireo, fa tsy "tsy amin'izao fotoana izao". Valio 2xx haingana ary ataovy avy eo ny asa; tapitra ny fe-potoana fanaterana rehefa afaka 10 segondra.

Hetsika misy

7. Hadisoana & kaody sata

8. Fanamarihana momba ny fiarovana

• Tsy afaka manova na inona na inona ny lakile famakiana ihany (mp_ro_). Tsy afaka afa-tsy mampifandray ID mpanjifa ny lakile fanoratana (mp_rw_); tsy misy lakile afaka mamafa angona na manondrana angona manta famerenana.
• Voafetra ho azy amin'ny sehatra fiasan'ilay lakile ihany ny fangatahana tsirairay — tsy misy fomba handefasana ID sehatra fiasana hafa ka hahitana ny angon'olon-kafa.
• Foano amin'ny fotoana rehetra ny lakile ao amin'ny /api-keys; mihatra avy hatrany ny fanafoanana.
• Raiso ho toy ny tenimiafina ny lakile API anao. Raha nampidirinao tsy nahy tao amin'ny tahiry kaody ampahibemaso izy dia foano avy hatrany ary mamoròna vaovao.