Ашық API & API кілттері

1. Шолу

MousePlayer API жұмыс кеңістігіңізден деректерді өз басқару тақталарыңызға, деректер қоймасына немесе ішкі құралдарға алуға мүмкіндік береді. Сеанстарға тұтынушы ID-ін қосудан басқа (identify, жазу ауқымы бар кілт қажет, «Кілт ауқымдары» бөлімін қараңыз), ол тек оқуға арналған: API арқылы деректерді өзгерту не жою мүмкін емес.

• Негізгі URL: https://www.mouseplayer.com/api/v1/
• Барлық жауап JSON түрінде.
• Әр сұрау API кілтімен расталып, сол кілт тиесілі жұмыс кеңістігімен автоматты шектеледі — бір жұмыс кеңістігінің кілті басқа кеңістіктің деректерін кездейсоқ та көре алмайды.
• Толық сеанс қайта ойнату жазбасы (тінтуір қозғалыстары, DOM суреттері) API арқылы берілмейді . Сеанс метадеректерін, бет қаралымдарын, арнайы оқиғалар мен сегменттерді аласыз — өңделмеген қайта ойнату деректерін тасымалдамай есептер мен тақталар жасауға жеткілікті.

2. Аутентификация

API кілттерін есептік жазба мәзіріндегі API кілттері бөлімінде жасаңыз және басқарыңыз (/api-keys). Кілттерді тек жұмыс кеңістігінің иелері мен әкімшілері жасай немесе күшін жоя алады.

Кілтті әр сұраудың мына тақырыбында Bearer токені ретінде жіберіңіз: Authorization :

Жоқ, қате пішімдегі немесе күші жойылған кілттер мына жауапты алады: 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. Вебхуктар: қолтаңбаны тексеру

Вебхуктар әр жобаның Интеграцияларбөлімінде бапталады, қол қою құпиясы да сонда. Әр жеткізілімде мына тақырыптар бар:

Қолтаңба — мына деректер бойынша есептелген 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_) тек клиент идентификаторларын тіркей алады; ешбір кілт деректерді жоя алмайды немесе бастапқы қайта ойнату деректерін экспорттай алмайды.
• Әр сұрау автоматты түрде кілттің өз жұмыс кеңістігімен шектеледі — басқа жұмыс кеңістігінің идентификаторын беріп, бөтен деректерді көру мүмкін емес.
• Кілтті кез келген уақытта мына жерден қайтарып алыңыз: /api-keys; қайтарып алу бірден күшіне енеді.
• API кілтін құпиясөздей сақтаңыз. Оны байқамай ашық репозиторийге коммиттесеңіз, бірден қайтарып алып, жаңасын жасаңыз.