API-ga dadweynaha & furayaasha API

1. Dulmar

API-ga MousePlayer wuxuu kuu oggolaanayaa inaad xogta goobtaada shaqada u soo qaadato dashboards-kaaga, bakhaarkaaga xogta ama qalabkaaga gudaha. Marka laga reebo ku-lifaaqidda ID-yada macaamiisha fadhiyada (identify, wuxuu u baahan yahay fure leh baaxad qoritaan, eeg Baaxadaha furaha) waa akhris keliya: xog laguma beddeli karo ama laguma tirtiri karo API-ga.

• URL-ka aasaasiga ah: https://www.mouseplayer.com/api/v1/
• Dhammaan jawaabuhu waa JSON.
• Codsi kasta waxaa lagu xaqiijiyaa fure API, si otomaatig ahna wuxuu ugu xaddidan yahay goobta shaqada ee furuhu ka tirsan yahay — fure goob shaqo ka yimid waligiis ma arki karo xogta goob shaqo kale, xitaa si kama' ah.
• Duubista dib-u-ciyaarista fadhiga oo dhan (dhaqdhaqaaqyada jiirka, sawirrada DOM) laguma soo bandhigo API-ga. Waxaad helaysaa metadata fadhiga, daawashooyinka bogga, dhacdooyinka gaarka ah iyo qaybaha — ku filan dhisidda warbixinno iyo dashboards iyadoon payload-ka dib-u-ciyaarista ceeriin ah la wareejin.

2. Xaqiijinta aqoonsiga

Abuur oo maamul furayaashaada API hoosta Furayaasha API ee menu-ga akoonkaaga (/api-keys). Milkiilayaasha iyo maamulayaasha goobta shaqada oo keliya ayaa abuuri kara ama kala noqon kara furayaal.

Furaha u dir sida Bearer token gudaha header-ka Authorization ee codsi kasta:

Furayaal maqan, qaab khaldan ama laga noqday waxay helaan jawaab 401 ah:

Shuruudda qorshaha

REST API wuxuu ka tirsan yahay qorshayaasha Business iyo Enterprise . Qorshaha waxaa laga qaataa milkiilaha goobta shaqada, sidaas darteed xubnaha kooxda ee la casuumay way dhaxlaan. Hubintu waxay socotaa codsi kasta, ma aha oo keliya marka fure la abuurayo — haddii goob shaqo loo dhimo qorshe hoose, furayaasha jira way joogsadaan oo soo celiyaan 403.

Baaxadaha furaha

Fure kastaa baaxaddiisa wuxuu ku wataa horgalihiisa, si aad u ogaato waxa fure samaynayo markaad eegto oo keliya — gudaha .env, ticket ama terminal.

3. Xadadka codsiyada

Fure API kasta wuxuu ku xaddidan yahay 60 codsi daqiiqaddii, oo lagu dabagalo daaqad dhaqaaqaysa. Marka aad taas dhaafto, codsiyadu waxay helaan jawaab 429 ah ilaa daaqaddu banneyso:

4. Endpoints

GET/api/v1/projects

Wuxuu taxaa mashruuc kasta (websayt la dabagalo) oo goobtaada shaqada ku jira.

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

Wuxuu taxaa fadhiyada booqdayaasha ee mashruuc loo duubay, kuwa ugu cusub marka hore. Bogag loo qaybiyay.

GET/api/v1/sessions/{session_id}

Metadata hal fadhi iyo daawashooyinkiisa bogga. Si ula kac ah ayuu uga reebaa payload-ka dib-u-ciyaarista oo dhan — taas u adeegso Ciyaariyaha dashboard-ka.

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

Dhacdooyinka gaarka ah ee dhacay inta fadhi socdo (isla dhacdooyinka aad ku dirto mp('event', ...)), oo ay ku jiraan halbeegyadoodu.

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

Wuxuu taxaa qaybaha booqdayaasha ee mashruuc loo qeexay (qaybaha mashruuca gaarka u ah iyo kuwa goobta shaqada oo dhan).

5. Ku-lifaaqidda ID macmiil backend-kaaga

Biraawsarku badanaa ma yaqaan cidda fadhida. Badeecad B2B ah, aqoonsiga waxaa la go'aamiyaa gelitaanka ka dib — backend-kaaga. Dukaan, waxaa la go'aamiyaa marka dalabka la xaqiijiyo. Endpoint-kan waxaa loogu talagalay isla waqtigaas.

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

ID-gu dabadeed wuxuu ka muuqdaa liiska fadhiyada, halkaas ayaa laga raadin karaa, webhook-ga session_identified na wuu shaqeeyaa — sidaas ayuu CRM-kaaga ku gaaraa.

6. Webhooks: xaqiijinta saxiixa

Webhooks mashruuc kasta waxaa looga dejiyaa Isku-xirrada, halkaas oo aad sidoo kale ka hesho sirta saxiixa. Gudbin kastaa waxay wadataa headers-kan:

Saxiixu waa HMAC-SHA256 oo lagu sameeyay timestamp + "." + raw body, iyadoo furaha laga dhigayo sirta saxiixa ee mashruucaaga.

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

Gudbinta iyo isku-dayada dambe

Gudbin fashilantay waxaa mar kale la isku dayaa ka dib 1 min, 5 min, 15 min, 1 h iyo 6 h, dabadeed waa laga quustaa. 4xx Jawaabaha 408 iyo 429 ka duwan ee laguma celiyo isku day — waxay sheegayaan "sidan ma aha", ma aha "hadda ma aha". Si degdeg ah ugu jawaab 2xx shaqadana dabadeed samee; gudbintu waxay waqtigeedu dhammaataa 10 ilbiriqsi ka dib.

Dhacdooyinka la heli karo

7. Khaladaad & koodhadhka xaaladda

8. Qoraallo amni

• Furayaasha akhris-keliya ah (mp_ro_) waxba ma beddeli karaan. Furayaasha qora (mp_rw_) waxay ku lifaaqi karaan oo keliya ID-yada macaamiisha; fure ma tirtiri karo xog ama ma dhoofin karo xogta dib-u-ciyaarista ceeriin ah.
• Codsi kasta si otomaatig ah wuxuu ugu xaddidan yahay goobta shaqada ee furaha — ma jiro hab aad u gudbin karto ID goob shaqo oo kale oo aad arki karto xog qof kale.
• Fure wakhti kasta kala noqo /api-keys; kala-noqoshadu isla markiiba ayay dhaqan gashaa.
• Furahaaga API ula dhaqan sida eray sir ah. Haddii aad si kama' ah ugu commit-garayso repository dadweyne ah, isla markiiba kala noqo oo abuur mid cusub.