Жалпы 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 Business жана Enterprise тарифтерине кирет. Тариф жумуш мейкиндигинин ээсинен алынат, ошондуктан чакырылган топ мүчөлөрү да аны колдонот. Текшерүү ачкыч түзүлгөндө гана эмес, ар бир сурамда жүргүзүлөт — жумуш мейкиндигинин тарифи төмөндөтүлсө, бар ачкычтар иштебей, 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 вебхугу иштейт — ал CRMиңизге ушинтип жетет.

6. Вебхуктар: кол тамганы текшерүү

Вебхуктар ар бир долбоордун Интеграциялар бөлүмүндө жөндөлөт; ал жерде кол коюу сыры да бар. Ар бир жеткирүүдө төмөнкү аталыштар болот:

Кол тамга — timestamp + "." + raw body боюнча долбооруңуздун кол коюу сыры менен түзүлгөн HMAC-SHA256.

// 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 ачкычын сырсөздөй сактаңыз. Кокус жалпыга ачык репозиторийге коммит кылсаңыз, дароо жокко чыгарып, жаңысын түзүңүз.