API ya giştî & mifteyên API

1. Pêşdîtin

API ya MousePlayer dihêle hûn daneyan ji qada xebata xwe derxin û bixin panelên kontrolê, depoya daneyan an amûrên xwe yên navxweyî. Ji bilî zêdekirina ID yên mişteriyan li danişînan (identify, mifteyeke bi destûra nivîsandinê hewce dike, li Destûrên mifteyan binêrin), ew tenê ji bo xwendinê ye: bi rêya API tu dane nayên guhertin an rakirin.

• URL ya bingehîn: https://www.mouseplayer.com/api/v1/
• Hemû bersiv JSON in.
• Her daxwaz bi mifteyeke API tê piştrastkirin û bixweber bi qada xebata ku mifte jê re ye tê sînorkirin — mifteyeke ji qadeke xebatê qet nikare daneyên qadeke din bibîne, heta bi xeletî jî.
• Tevahiya tomara ji nû ve lîstina danişînê (tevgerên mişkê, wêneyên DOM) bi rêya API nayê pêşkêşkirin. Hûn metadaneyên danişînê, dîtinên rûpelê, bûyerên taybet û segmentan werdigirin — têrê çêkirina rapor û panelên kontrolê dike, bê veguhastina barka xam a ji nû ve lîstinê.

2. Piştrastkirin

Mifteyên API yên xwe di beşa Mifteyên API ya pêşeka hesabê xwe de çêkin û bi rê ve bibin (/api-keys). Tenê xwedî û rêvebirên qada xebatê dikarin mifteyan çêkin an rakin.

Mifteyê wek tokena Bearer di sernavê Authorization yê her daxwazê de bişînin:

Mifteyên kêm, bi teşeya xelet an hatine rakirin bersiva 401 werdigirin:

Pêdiviya planê

REST API beşek ji planên Business û Enterprise e. Plan ji xwediyê qada xebatê tê standin, lewma endamên tîmê yên vexwendî wê werdigirin. Kontrol di her daxwazê de tê kirin, ne tenê dema mifte tê çêkirin — ger qada xebatê li plana nizmtir were xistin, mifteyên heyî êdî naxebitin û 403 vedigerînin.

Destûrên mifteyan

Her mifte destûra xwe di pêşgira xwe de digire, lewma hûn tenê bi lênihêrînê dikarin bizanin mifte çi dike — di .env de, di bilêtekê de, di termînalê de.

3. Sînorên rêjeyê

Her mifteya API bi 60 daxwazan di deqeyekê de tê sînorkirin, di pencereyeke demê ya digere de tê şopandin. Dema hûn wê derbas bikin, daxwaz bersiva 429 werdigirin heta pencere vala bibe:

4. Xalên dawî

GET/api/v1/projects

Her projeya (malpera şopandî ya) di qada xebata we de lîste dike.

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

Danişînên serdankeran ên ji bo projeyekê hatine tomarkirin lîste dike, yên herî nû pêşî. Bi rûpelan parvekirî.

GET/api/v1/sessions/{session_id}

Metadaneyên danişîneke tenê, bi dîtinên rûpelê yên wê re. Bi qestî barka tevahî ya ji nû ve lîstinê nagire — ji bo wê lêdara panela kontrolê bikar bînin.

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

Bûyerên taybet ên di danişînekê de hatine çalakkirin (heman bûyerên ku hûn bi mp('event', ...) dişînin), bi parametreyên wan re.

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

Segmentên serdankeran ên ji bo projeyekê hatine pênasekirin lîste dike (hem segmentên taybet ên projeyê hem yên tevahiya qada xebatê).

5. Zêdekirina ID ya mişterî ji backendê we

Gerok gelek caran nizane ka kî li wir rûniştiye. Di hilbereke B2B de nasname piştî têketinê diyar dibe — di backendê we de. Di dikanekê de ew bi piştrastkirina fermanê diyar dibe. Ev xala dawî tam ji bo wê kêliyê ye.

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

Paşê ID di lîsteya danişînan de xuya dibe, li wir tê lêgerîn û webhooka session_identified çalak dibe — bi vî awayî ew digihîje CRM ya we.

6. Webhook: piştrastkirina îmzayê

Webhook ji bo her projeyê di bin Girêdan de tên veavakirin; li wir hûn neheniya îmzekirinê jî dibînin. Her şandin van sernavan digire:

Îmze HMAC-SHA256 li ser timestamp + "." + raw body e, bi neheniya îmzekirinê ya projeya we wek mifte.

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

Şandin û hewldanên ji nû ve

Şandina têkçûyî piştî 1 deq, 5 deq, 15 deq, 1 saet û 6 saet ji nû ve tê ceribandin, paşê tê devjêberdan. 4xx bersivên ji bilî 408 û 429 ji nû ve nayên ceribandin — ew dibêjin "ne wisa", ne "ne niha". Bi 2xx zû bersiv bidin û karê xwe paşê bikin; şandin piştî 10 çirkeyan sînorê demê derbas dike.

Bûyerên berdest

7. Çewtî & kodên rewşê

8. Têbîniyên ewlehiyê

• Mifteyên tenê xwendinê (mp_ro_) nikarin tiştekî biguherînin. Mifteyên nivîsandinê (mp_rw_) tenê dikarin ID yên mişteriyan zêde bikin; tu mifte nikare daneyan rake an daneyên xam ên ji nû ve lîstinê derxe.
• Her daxwaz bixweber bi qada xebatê ya mifteyê bixwe tê sînorkirin — rêyek tune ye ku ID ya qadeke din derbas bikin û daneyên kesekî din bibînin.
• Hûn dikarin her dem mifteyê ji /api-keys rakin; rakirin tavilê bandor dike.
• Mifteya API wek şîfreyê bibînin. Ger hûn bi xeletî yekê di depoyeke giştî de commit bikin, wê tavilê rakin û ya nû çêkin.