Açıq API & API açarları

1. İcmal

MousePlayer API məlumatları iş sahənizdən öz idarə panellərinizə, məlumat anbarınıza və ya daxili alətlərinizə çıxarmağa imkan verir. Müştəri ID-lərinin seanslara bağlanması (identify, yazma səlahiyyətli açar tələb edir, Açar səlahiyyətlərinə baxın) istisna olmaqla yalnız oxumaüçündür: API vasitəsilə heç bir məlumat dəyişdirilə və ya silinə bilməz.

• Əsas URL: https://www.mouseplayer.com/api/v1/
• Bütün cavablar JSON-dur.
• Hər sorğu API açarı ilə autentifikasiya olunur və avtomatik həmin açarın aid olduğu iş sahəsi ilə məhdudlaşır — bir iş sahəsinin açarı başqa iş sahəsinin məlumatını təsadüfən belə görə bilməz.
• Tam seans təkrar oynatma qeydi (siçan hərəkətləri, DOM anlıq görüntüləri) API vasitəsilə təqdim edilmir . Seans metaməlumatlarını, səhifə baxışlarını, fərdi hadisələri və seqmentləri alırsınız — xam təkrar oynatma yükünü daşımadan hesabat və idarə panelləri qurmaq üçün kifayətdir.

2. Autentifikasiya

API açarlarınızı hesab menyunuzda bu bölmədə yaradın və idarə edin: API açarları (/api-keys). Açarları yalnız iş sahəsinin sahibləri və adminlər yarada və ya ləğv edə bilər.

Açarı hər sorğunun bu başlığında Bearer tokeni kimi göndərin: Authorization :

Çatışmayan, yanlış formatlı və ya ləğv edilmiş açarlar bu cavabı alır: 401 :

Plan tələbi

REST API bu planlara daxildir: Business və Enterprise . Plan iş sahəsinin sahibindən götürülür, buna görə dəvət edilmiş komanda üzvləri də ondan yararlanır. Yoxlama yalnız açar yaradılarkən deyil, hər sorğudaişləyir — iş sahəsinin planı aşağı salınsa, mövcud açarlar dayanıb bunu qaytarır: 403.

Açar səlahiyyətləri

Hər açar səlahiyyətini öz prefiksində daşıyır, buna görə ona baxmaqla nə etdiyini bilmək olar — bu yerdə: .env, sorğuda və ya terminalda.

3. Sorğu tezliyi limitləri

Hər API açarı bu limitlə məhdudlaşdırılır: dəqiqədə 60 sorğu, sürüşən zaman aralığı üzrə izlənir. Aşdıqdan sonra aralıq boşalanadək sorğular bu cavabı alır: 429 :

4. Son nöqtələr

GET/api/v1/projects

İş sahənizdəki bütün layihələri (izlənən resursları) siyahıya alır.

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

Layihə üçün qeydə alınmış ziyarətçi seanslarını, ən yenilər əvvəl olmaqla siyahıya alır. Səhifələnir.

GET/api/v1/sessions/{session_id}

Tək seansın metaməlumatları və səhifə baxışları. Tam təkrar oynatma yükü qəsdən daxil deyil — onun üçün idarə panelinin pleyerindən istifadə edin.

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

Seans ərzində baş vermiş fərdi hadisələr (bu üsulla göndərdiyiniz eyni hadisələr: mp('event', ...)), parametrləri ilə birlikdə.

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

Layihə üçün müəyyən edilmiş ziyarətçi seqmentlərini (həm layihəyə xüsusi, həm də bütün iş sahəsi üzrə) siyahıya alır.

5. Arxa tərəfinizdən müştəri ID-si bağlamaq

Brauzer çox vaxt qarşısında kimin olduğunu bilmir. B2B məhsulunda kimlik girişdən sonra — arxa tərəfinizdə müəyyənləşir. Mağazada sifariş təsdiqi ilə müəyyənləşir. Bu son nöqtə məhz həmin an üçündür.

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

Sonra ID seans siyahısında görünür, orada axtarıla bilir və bu vebhuk: session_identified işə düşür — CRM sisteminizə belə çatır.

6. Vebhuklar: imzanın yoxlanması

Vebhuklar hər layihə üçün bu bölmədə tənzimlənir: İnteqrasiyalar, imzalama sirrini də orada tapırsınız. Hər çatdırılma bu başlıqları daşıyır:

İmza bu mətn üzərində HMAC-SHA256-dır: timestamp + "." + raw body, layihənizin imzalama sirri açar kimi istifadə olunur.

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

Çatdırılma və təkrar cəhdlər

Uğursuz çatdırılma bu fasilələrlə yenidən sınanır: 1 dəq, 5 dəq, 15 dəq, 1 saat və 6 saat, sonra cəhdlər dayandırılır. 4xx Bu cavablardan başqa: 408 və 429 olan cavablar yenidən sınanmır — onlar "belə olmaz" deyir, "indi olmaz" deyil. Tez bu cavabı verin: 2xx və işi sonra görün; çatdırılma 10 saniyədən sonra vaxt limitinə çatır.

Əlçatan hadisələr

7. Xətalar & vəziyyət kodları

8. Təhlükəsizlik qeydləri

• Yalnız oxuma açarları (mp_ro_) heç nəyi dəyişə bilməz. Yazma açarları (mp_rw_) yalnız müştəri ID-lərini bağlaya bilər; heç bir açar məlumat silə və ya xam təkrar oynatma məlumatlarını ixrac edə bilməz.
• Hər sorğu avtomatik açarın öz iş sahəsi ilə məhdudlaşır — başqa iş sahəsinin ID-sini ötürüb başqasının məlumatlarını görmək mümkün deyil.
• Açarı istənilən vaxt bu səhifədən ləğv edin: /api-keys; ləğv dərhal qüvvəyə minir.
• API açarınıza parol kimi yanaşın. Təsadüfən açıq repozitoriyaya əlavə etsəniz, dərhal ləğv edib yenisini yaradın.