Açyk API & API açarlary

1. Umumy syn

MousePlayer API iş meýdançaňyzdaky maglumatlary öz dolandyryş panelleriňize, maglumat ammaryňyza ýa-da içerki gurallaryňyza almaga mümkinçilik berýär. Sessiýalara müşderi ID-lerini baglamakdan başga (identify, ýazuw ygtyýarly açar gerek, Açar ygtyýarlyklaryna serediň) ol diňe okamak üçin niýetlenendir: API arkaly maglumatlary üýtgetmek ýa-da pozmak mümkin däl.

• Esasy URL: https://www.mouseplayer.com/api/v1/
• Ähli jogaplar JSON görnüşindedir.
• Her talap API açary bilen tassyklanýar we awtomatik usulda şol açaryň degişli iş meýdançasy bilen çäklendirilýär — bir iş meýdançasynyň açary başga iş meýdançasynyň maglumatlaryny hatda tötänden hem görüp bilmeýär.
• Sessiýanyň doly gaýtadan görkeziliş ýazgysy (syçanjygyň hereketleri, DOM suratlary) API arkaly elýeterli däl . Sessiýa meta-maglumatlaryny, sahypa görnüşlerini, ýörite wakalary we segmentleri alýarsyňyz — çig gaýtadan görkeziliş maglumatlaryny daşamazdan hasabatlary we dolandyryş panellerini gurmak üçin ýeterlikdir.

2. Autentifikasiýa

API açarlaryňyzy hasap menýusyndaky API açarlary bölüminde dörediň we dolandyryň (/api-keys). Açarlary diňe iş meýdançasynyň eýeleri we administratorlary döredip ýa-da ýatyryp bilýär.

Açary her talabyň Authorization sözbaşysynda Bearer tokeni hökmünde iberiň:

Ýok, nädogry formatdaky ýa-da ýatyrylan açarlar şu jogaby alýar: 401

Nyrhnama talaby

REST API şu nyrhnamalaryň düzümine girýär: Business we Enterprise . Nyrhnama iş meýdançasynyň eýesinden alynýar, şonuň üçin çagyrylan topar agzalary hem şondan peýdalanýar. Barlag her talapda geçirilýär, diňe açar döredilende däl — iş meýdançasy pes nyrhnama geçirilse, bar bolan açarlar işlemegini bes edip, şu jogaby gaýtarýar: 403.

Açar ygtyýarlyklary

Her açaryň ygtyýarlygy onuň öz prefiksinde görkezilýär, şonuň üçin açara seredip onuň näme edýändigini bilip bilersiňiz — .env içinde, ýüz tutmada ýa-da terminalda.

3. Talap ýygylygynyň çäkleri

Her API açary üçin çäk minutda 60 talapdyr we süýşýän wagt penjiresinde hasaplanýar. Çäkden geçseňiz, wagt penjiresi boşanýança talaplar şu jogaby alýar: 429

4. Ahyrky nokatlar

GET/api/v1/projects

Iş meýdançaňyzdaky ähli taslamalary (yzarlanylýan çeşmeleri) sanap berýär.

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

Taslama üçin ýazga alnan myhman sessiýalaryny iň täzesinden başlap sanap berýär. Sahypalara bölünýär.

GET/api/v1/sessions/{session_id}

Bir sessiýanyň meta-maglumatlary we sahypa görnüşleri. Doly gaýtadan görkeziliş maglumatlary bilgeşleýin goşulmaýar — munuň üçin dolandyryş paneliniň pleýerini ulanyň.

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

Sessiýa wagty ýüze çykan ýörite wakalar (şu usul bilen iberýän wakalaryňyz: mp('event', ...)), olaryň parametrleri bilen bilelikde.

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

Taslama üçin kesgitlenen myhman segmentlerini sanap berýär (taslama mahsus hem-de tutuş iş meýdançasyna degişli segmentler).

5. Serweriňizden müşderi ID-sini baglamak

Brauzer köplenç onuň öňünde kimiň oturandygyny bilmeýär. B2B önüminde şahsyýet ulgama girilenden soň — serweriňizde kesgitlenýär. Dükanda ol sargyt tassyklananda kesgitlenýär. Bu ahyrky nokat hut şol pursat üçin niýetlenendir.

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

Soňra ID sessiýa sanawynda görünýär, şol ýerde gözlenip bolýar we session_identified webhook-y işe düşýär — CRM ulgamyňyza hem şeýdip ýetýär.

6. Webhook-lar: goly barlamak

Webhook-lar her taslama üçin Birikdirmeler bölüminde sazlanýar; gol goýmak üçin gizlin açar hem şol ýerde. Her iberiş şu sözbaşylary öz içine alýar:

Gol şu mazmunyň HMAC-SHA256 bahasydyr: timestamp + "." + raw body, açar hökmünde taslamaňyzyň gol goýmak üçin gizlin açary ulanylýar.

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

Iberiş we gaýtadan synanyşyklar

Şowsuz iberişden soň şu aralyklarda gaýtadan synanyşylýar: 1 min, 5 min, 15 min, 1 sagat we 6 sagat, soňra synanyşyklar bes edilýär. 4xx jogaplary, 408 we 429 ýagdaýlaryndan başga, gaýtadan synanyşylmaýar — olar "beýle däl" diýýär, "häzir däl" däl. Çalt jogap beriň: 2xx we işi soň ýerine ýetiriň; iberişiň wagt çägi 10 sekuntdyr.

Elýeterli wakalar

7. Ýalňyşlyklar & ýagdaý kodlary

8. Howpsuzlyk bellikleri

• Diňe okamak açarlary (mp_ro_) hiç zady üýtgedip bilmeýär. Ýazuw açarlary (mp_rw_) diňe müşderi ID-lerini baglap bilýär; hiç bir açar maglumatlary pozup ýa-da çig gaýtadan görkeziliş maglumatlaryny eksport edip bilmeýär.
• Her talap awtomatik usulda açaryň öz iş meýdançasy bilen çäklendirilýär — başga iş meýdançasynyň ID-sini geçirip, başga biriniň maglumatlaryny görmek mümkin däl.
• Açary islendik wagt şu ýerden ýatyryň: /api-keys; ýatyrmak dessine güýje girýär.
• API açaryňyzy parol ýaly goraň. Ony tötänden açyk ammara commit etseňiz, dessine ýatyryň we täzesini dörediň.