API uummataaf banaa & furtuuwwan API

1. Cuunfaa

API MousePlayer deetaa iddoo hojii keessan keessaa gara daashboordii, mana kuusaa deetaa yookaan meeshaa keessaa mataa keessaniitti akka baafattan taasisa. ID maamilaa turtii irratti dabaluun alatti (identify, furtuu daangaa barreessuu qabu barbaada, Daangaa furtuu ilaalaa) inni dubbisuu qofadha: deetaan karaa API jijjiiramuu yookaan haqamuu hin danda'u.

• URL bu'uuraa: https://www.mouseplayer.com/api/v1/
• Deebiin hundi JSON dha.
• Gaaffiin hundi furtuu API tiin eenyummaa mirkaneeffatee ofumaan iddoo hojii furtuun sun kan isaa ta'etti daangeffama — furtuun iddoo hojii tokkoo deetaa iddoo hojii biraa gonkumaa arguu hin danda'u, dogoggoraan illee.
• Waraabbiin irra deebi'anii taphachiisuu turtii guutuu (sochii maawusii, suuraalee DOM) API keessatti hin argamu. Metadata turtii, mul'ata fuulaa, taateewwan dhuunfaa fi kutaawwan argattu — deetaa irra deebi'anii taphachiisuu jalqabaa asii achi erguu malee gabaasa fi daashboordii ijaaruuf gahaa.

2. Mirkaneessa eenyummaa

Furtuuwwan API keessan menu herregaa keessatti kan Furtuuwwan API jalatti uumaa bulchaa (/api-keys). Abbootii iddoo hojii fi bulchitoota qofa furtuu uumuu yookaan haquu danda'u.

Furtuu akka tookanii Bearer tti mataa Authorization gaaffii hunda keessatti ergaa:

Furtuun dhabame, bifa dogoggoraa qabu yookaan haqame deebii 401 argata:

Ulaagaa karooraa

REST API kutaa karoora Business fi Enterprise ti. Karooraan abbaa iddoo hojii irraa fudhatama, kanaaf miseensonni garee affeeraman dhaalu. Qorannoon gaaffii hunda irrattihojjeta, furtuun yeroo uumamu qofa miti — iddoo hojii gadi yoo buufame, furtuun jiru hojjechuu dhaabee 403deebisa.

Daangaa furtuu

Furtuun hundi daangaa isaa durgoo mataa isaa keessatti qaba, kanaaf furtuun maal akka godhu ilaaluun qofa beekuu dandeessu — kana keessatti .env, tikettii keessatti, terminal keessatti.

3. Daangaa baay'ina gaaffii

Furtuun API hundi gaaffii 60 daqiiqaattidaangeffama, foddaa yeroo socho'u keessatti lakkaa'ama. Yoo caaltan, gaaffiiwwan deebii 429 hanga foddaan qulqullaa'utti argatu:

4. Bakkeewwan xumuraa

GET/api/v1/projects

Pirojektii (marsariitii hordofamu) iddoo hojii keessan keessaa hunda tarreessa.

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

Turtii daawwataa pirojektiif waraabame tarreessa, haaraa dura. Fuulaan qoodame.

GET/api/v1/sessions/{session_id}

Metadata turtii tokkoo, dabalataan mul'ata fuulaa isaa. Of eeggannoon deetaa irra deebi'anii taphachiisuu guutuu keessaa baasa — sanaaf Taphachiisaa daashboordii fayyadamaa.

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

Taateewwan dhuunfaa turtii keessatti kakaafaman (taateewwan walfakkaataa isin kanaan ergitan mp('event', ...)), parametaroota isaanii dabalatee.

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

Kutaawwan daawwataa pirojektiif ibsaman tarreessa (kan pirojektii addaa fi iddoo hojii guutuu lamaan).

5. ID maamilaa gama duubaa keessan irraa dabaluun

Biraawzariin eenyutu achi akka taa'u yeroo baay'ee hin beeku. Oomisha B2B keessatti eenyummaan seensa booda murtaa'a — gama duubaa keessan keessatti. Suuqii keessatti mirkaneessa ajajaatiin murtaa'a. Bakki xumuraa kun sirriitti yeroo sanaaf.

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

IDn sana booda tarree turtii keessatti mul'ata, achittis barbaadamuu danda'a, webhook session_identified kaka'a — akkasitti CRM keessan ga'a.

6. Webhook: mallattoo mirkaneessuu

Webhook pirojektii tokkoon kan Walitti makuujalatti qindaa'a, achitti iccitii mallatteessuus argattu. Geejjibni hundi mataawwan kana qaba:

Mallattoon HMAC-SHA256 kan timestamp + "." + raw body, iccitii mallatteessaa pirojektii keessaniitiin furtuu ta'e.

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

Geejjibaa fi irra deebi'anii yaaluu

Geejjibni kufe 1 min, 5 min, 15 min, 1 h fi 6 hbooda irra deebi'ee yaalama, sana booda dhiifama. 4xx Deebiiwwan kanneen 408 fi 429 irraa adda ta'an hin yaalaman irra deebi'anii — isaan "akkas miti" jedhu, "amma miti" miti. Saffisaan 2xx deebisaa hojii sana booda hojjedhaa; geejjibni sekondii 10 booda yeroon isaa dhuma.

Taateewwan argaman

7. Dogoggoroota & koodii haalaa

8. Yaadannoo nageenyaa

• Furtuun dubbisuu qofa (mp_ro_) homaa jijjiiruu hin danda'u. Furtuun barreessuu (mp_rw_) ID maamilaa qofa dabalu danda'a; furtuun kamiyyuu deetaa haquu yookaan deetaa irra deebi'anii taphachiisuu jalqabaa erguu hin danda'u.
• Gaaffiin hundi ofumaan iddoo hojii furtuu mataa isaatti daangeffama — karaa ID iddoo hojii adda ta'e dabarsanii deetaa nama biraa itti argan hin jiru.
• Yeroo kamiyyuu furtuu kana irraa haqaa /api-keys; haqamuun battalumatti hojiirra oola.
• Furtuu API keessan akka jecha darbiitti qabaa. Dogoggoraan kuusaa koodii uummataaf banaa keessatti yoo commit gootan, battalumatti haqaa haaraa uumaa.