Нийтийн API & API түлхүүрүүд

1. Тойм

MousePlayer API нь ажлын орчноосоо өгөгдөл авч өөрийн хяналтын самбар, өгөгдлийн агуулах эсвэл дотоод хэрэгсэлд ашиглах боломж олгоно. Сеансад харилцагчийн ID холбохоос бусад үйлдэл (identify, бичих хүрээтэй түлхүүр хэрэгтэй, түлхүүрийн хүрээг үзнэ үү) нь зөвхөн унших: API-аар ямар ч өгөгдөл өөрчлөх эсвэл устгах боломжгүй.

• Үндсэн URL: https://www.mouseplayer.com/api/v1/
• Бүх хариу JSON хэлбэртэй.
• Хүсэлт бүр API түлхүүрээр баталгаажиж, түлхүүрийн харьяалагдах ажлын орчноор автоматаар хязгаарлагдана — нэг ажлын орчны түлхүүр нөгөөгийн өгөгдлийг санамсаргүйгээр ч хэзээ ч харахгүй.
• Сеансын бүтэн дахин тоглуулах бичлэг (хулганы хөдөлгөөн, DOM агшин зураг) API-аар нээлттэй биш . Та сеансын метаөгөгдөл, хуудас үзэлт, тусгай үйл явдал, сегмент авна — түүхий дахин тоглуулах өгөгдлийг дамжуулалгүйгээр тайлан, хяналтын самбар бүтээхэд хангалттай.

2. Баталгаажуулалт

API түлхүүрүүдээ бүртгэлийн цэсийн дараах хэсэгт үүсгэж удирдана уу: API түлхүүрүүд (/api-keys). Зөвхөн ажлын орчны эзэмшигч болон админ түлхүүр үүсгэх эсвэл хүчингүй болгох эрхтэй.

Түлхүүрийг хүсэлт бүрийн дараах Authorization толгой хэсэгт Bearer токен болгон илгээнэ үү:

Дутуу, буруу хэлбэртэй эсвэл хүчингүй болгосон түлхүүр дараах 401 хариуг авна:

Багцын шаардлага

REST API нь дараах багцуудад багтана: Бизнес болон Байгууллагын . Багцыг ажлын орчны эзэмшигчээс авдаг тул уригдсан багийн гишүүд өвлөн ашиглана. Шалгалт хүсэлт бүрд хийгдэнэ, зөвхөн түлхүүр үүсгэхэд биш — ажлын орчны багцыг бууруулбал одоогийн түлхүүрүүд ажиллахаа больж, дараахыг буцаана: 403.

Түлхүүрийн хүрээ

Түлхүүр бүр хүрээгээ өөрийн угтвартаа агуулдаг тул хараад л юу хийдгийг мэдэж болно — дараахад, .env, хүсэлтэд эсвэл терминалд.

3. Хүсэлтийн давтамжийн хязгаар

API түлхүүр бүр минутанд 60 хүсэлтээр хязгаарлагдана. Хөдөлгөөнт цонхоор тоолно. Хэтрүүлбэл цонх цэвэрлэгдэх хүртэл хүсэлтүүд дараах 429 хариуг авна:

4. Төгсгөлийн цэгүүд

GET/api/v1/projects

Ажлын орчны бүх төслийг (хянаж буй сайтууд) жагсаана.

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

Төсөлд бүртгэсэн зочны сеансуудыг шинэ нь эхэнд, хуудсаар жагсаана.

GET/api/v1/sessions/{session_id}

Нэг сеансын метаөгөгдөл болон хуудас үзэлтүүд. Дахин тоглуулах бүтэн өгөгдлийг зориуд хассан — үүнд хяналтын самбарын тоглуулагчийг ашиглана уу.

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

Сеансын үеэр өдөөгдсөн тусгай үйл явдлууд (таны дараахаар илгээдэг ижил үйл явдлууд: mp('event', ...)), параметрүүдийнх нь хамт.

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

Төсөлд тодорхойлсон зочны сегментүүдийг жагсаана (тухайн төслийн болон ажлын орчин даяарх сегментүүд).

5. Серверээсээ харилцагчийн ID холбох

Хөтөч тэнд хэн сууж байгааг ихэвчлэн мэддэггүй. B2B бүтээгдэхүүнд нэвтэрсний дараа таны сервер дээр таних мэдээлэл тогтоно — дэлгүүрт захиалга баталгаажихад тогтоно. Энэ төгсгөлийн цэг яг тэр агшинд зориулагдсан.

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 сеансын жагсаалтад харагдаж, тэндээс хайх боломжтой болно. Дараах session_identified webhook өдөөгдөнө — ингэж CRM-д тань хүрнэ.

6. Webhook: гарын үсгийг шалгах

Webhook-уудыг төсөл тус бүрд дараах хэсэгт тохируулна: Интеграцчиллууд. Тэнд мөн гарын үсгийн нууц бий. Дамжуулалт бүр дараах толгой хэсгүүдтэй:

Гарын үсэг нь дараах дээрх HMAC-SHA256: timestamp + "." + raw body, таны төслийн гарын үсгийн нууцыг түлхүүр болгон ашиглана.

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

Дамжуулалт ба дахин оролдлого

Амжилтгүй дамжуулалтыг дараах хугацааны дараа дахин оролдоно: 1 мин, 5 мин, 15 мин, 1 цаг, 6 цаг. Дараа нь орхино. 4xx хариунуудаас дараах хоёрыг хасна: 408 болон 429 , бусдыг дахин илгээхгүй — тэд "одоо биш" гэхээсээ "ингэж биш" гэж хэлдэг. Дараах хариуг 2xx хурдан өгөөд ажлыг дараа нь хийнэ үү. Дамжуулалтын хугацаа 10 секундэд дуусна.

Боломжтой үйл явдлууд

7. Алдаа & төлөвийн кодууд

8. Аюулгүй байдлын тэмдэглэл

• Зөвхөн унших түлхүүр (mp_ro_) юу ч өөрчилж чадахгүй. Бичих түлхүүр (mp_rw_) зөвхөн харилцагчийн ID холбож чадна. Ямар ч түлхүүр өгөгдөл устгах эсвэл дахин тоглуулах түүхий өгөгдөл экспортлох боломжгүй.
• Хүсэлт бүр түлхүүрийн өөрийн ажлын орчноор автоматаар хязгаарлагдана — өөр ажлын орчны ID дамжуулж бусдын өгөгдлийг харах арга байхгүй.
• Дараах хэсгээс түлхүүрийг хүссэн үедээ хүчингүй болгоно уу: /api-keys. Хүчингүй болголт шууд үйлчилнэ.
• API түлхүүрээ нууц үг шиг хамгаална уу. Санамсаргүйгээр нийтийн репозиторт commit хийвэл нэн даруй хүчингүй болгож, шинээр үүсгэнэ үү.