Ochiq API & API kalitlari

1. Umumiy ko‘rinish

MousePlayer API ish maydoni ma’lumotini o‘z panel, ombor yoki ichki vositangizga olishga imkon beradi. Sessiyaga mijoz ID’sini qo‘shishdan tashqari (identify, yozish doirali kalit kerak, Kalit doiralariga qarang), u faqat o‘qish uchun: API orqali ma’lumotni o‘zgartirib yoki o‘chirib bo‘lmaydi.

• Asosiy URL: https://www.mouseplayer.com/api/v1/
• Barcha javoblar JSON.
• Har so‘rov API kaliti bilan tekshiriladi va avtomatik o‘sha kalit ish maydoniga cheklanadi — bir ish maydoni kaliti boshqasining ma’lumotini hatto tasodifan ham ko‘rolmaydi.
• To‘liq sessiya qayta ijro yozuvi (sichqoncha harakati, DOM tasvirlari) API orqali berilmaydi . Sessiya metama’lumoti, sahifa ko‘rishlar, maxsus hodisa va segmentlarni olasiz — xom ijro yuklamasini ko‘chirmasdan hisobot va panel yaratishga yetarli.

2. Autentifikatsiya

API kalitlarini hisob menyusidagi shu bo‘limda yarating va boshqaring: API kalitlari (/api-keys). Faqat ish maydoni egalari va administratorlar kalit yarata yoki bekor qila oladi.

Kalitni har so‘rovning shu Authorization sarlavhasida Bearer tokeni qilib yuboring:

Yo‘q, noto‘g‘ri yoki bekor kalitlar shu 401 javobini oladi:

Tarif talabi

REST API shu Business va Enterprise tariflariga kiradi. Tarif ish maydoni egasidan olinadi, taklif qilingan a’zolar meros oladi. Tekshiruv har so‘rovda, faqat kalit yaratilganda emas — tarif tushirilsa, mavjud kalitlar ishlamay, shuni qaytaradi: 403.

Kalit doiralari

Har kalit doirasi o‘z prefiksida, shuning uchun vazifasini qarab bilasiz — shu yerda: .env, so‘rovda yoki terminalda.

3. Tezlik limitlari

Har API kaliti shu bilan cheklangan: daqiqasiga 60 ta so‘rov, siljiydigan oraliqda kuzatiladi. Oshsangiz, oraliq tozalanguncha so‘rovlar shu 429 javobini oladi:

4. Endpoint’lar

GET/api/v1/projects

Ish maydoningizdagi har loyihani (kuzatilgan saytni) ro‘yxatlaydi.

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

Loyiha uchun yozilgan tashrifchi sessiyalarini avval yangilari bilan ro‘yxatlaydi. Sahifalangan.

GET/api/v1/sessions/{session_id}

Bitta sessiya metama’lumoti va sahifa ko‘rishlari. To‘liq qayta ijro yuklamasi ataylab yo‘q — buning uchun panel Pleyeridan foydalaning.

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

Sessiyada yuz bergan maxsus hodisalar (shu bilan yuborganlaringiz: mp('event', ...)), parametrlari bilan.

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

Loyiha uchun belgilangan tashrifchi segmentlarini ro‘yxatlaydi (loyihaga xos va ish maydoni bo‘ylab).

5. Backend’ingizdan mijoz ID’sini qo‘shish

Brauzer ko‘pincha kim o‘tirganini bilmaydi. B2B mahsulotda shaxs kirgach aniqlanadi — backend’da. Do‘konda buyurtma tasdig‘i bilan. Endpoint aynan shu payt uchun.

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 keyin sessiya ro‘yxatida ko‘rinadi, qidiriladi va shu session_identified webhook ishlaydi — CRM’ingizga shunday yetadi.

6. Webhook’lar: imzoni tekshirish

Webhook’lar har loyiha uchun shu yerda sozlanadi: Integratsiyalar, imzolash maxfiy kaliti ham o‘sha yerda. Har yetkazishda shu sarlavhalar bor:

Imzo HMAC-SHA256 bo‘lib, shu ustidan: timestamp + "." + raw body, loyiha imzolash maxfiy kalitingiz bilan kalitlangan.

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

Yetkazish va qayta urinishlar

Muvaffaqiyatsiz yetkazishdan keyin shu vaqtlarda qayta uriniladi: 1 daqiqa, 5 daqiqa, 15 daqiqa, 1 soat va 6 soat, keyin voz kechiladi. 4xx javoblari uchun, quyidagilar bundan mustasno: 408 va 429 , qayta urinilmaydi — ular "hozir emas" emas, "bunday emas" deydi. Shunday javob bering: 2xx tezda, ishni keyin qiling; yetkazish vaqti 10 soniyada tugaydi.

Mavjud hodisalar

7. Xatolar & holat kodlari

8. Xavfsizlik eslatmalari

• O‘qish kalitlari (mp_ro_) hech narsani o‘zgartira olmaydi. Yozish kalitlari (mp_rw_) faqat mijoz ID’sini qo‘sha oladi; hech bir kalit ma’lumotni o‘chira yoki xom qayta ijroni eksport qila olmaydi.
• Har so‘rov avtomatik kalitning o‘z ish maydoniga cheklanadi — boshqa ish maydoni ID’sini berib, o‘zga ma’lumotni ko‘rish yo‘li yo‘q.
• Kalitni istalgan payt shu yerda bekor qiling: /api-keys; bekor qilish darhol ta’sir qiladi.
• API kalitingizga paroldek qarang. Ochiq repozitoriyga tasodifan commit qilsangiz, darhol bekor qilib yangisini yarating.