საჯარო API & API გასაღებები

პროგრამული წვდომა თქვენს სამუშაო სივრცეზე — წაიკითხეთ პროექტები, სესიები, მორგებული მოვლენები და სეგმენტები, ხოლო სესიებს მომხმარებლის ID-ები მიამაგრეთ — სამუშაო სივრცით შემოსაზღვრული 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 სათაურში:

# List projects in your workspace curl -H "Authorization: Bearer mp_live_..." \ https://www.mouseplayer.com/api/v1/projects

დაკარგული, არასწორი ფორმატის ან გაუქმებული გასაღებები იღებს 401 პასუხს:

{ "error": "Invalid or missing API key. Use: Authorization: Bearer <key>" }

გეგმის მოთხოვნა

REST API შედის Business და Enterprise გეგმებში. გეგმა განისაზღვრება სამუშაო სივრცის მფლობელის მიხედვით, ამიტომ მოწვეული გუნდის წევრებიც მას იღებენ. შემოწმება სრულდება ყოველ მოთხოვნაზედა არა მხოლოდ გასაღების შექმნისას — თუ სამუშაო სივრცე დაბალ გეგმაზე გადავა, არსებული გასაღებები მუშაობას შეწყვეტს და დააბრუნებს 403.

გასაღების უფლებამოსილებები

ყოველი გასაღების უფლებამოსილება მის პრეფიქსში ჩანს, ამიტომ მხოლოდ შეხედვით გაიგებთ, რას აკეთებს — აქ: .env, ტიკეტში თუ ტერმინალში.

პრეფიქსი	მნიშვნელობა
`mp_ro_`	მხოლოდ წაკითხვა. კითხულობს პროექტებს, სესიებს, მოვლენებსა და სეგმენტებს. ვერაფერს ცვლის.
`mp_rw_`	წაკითხვა და ჩაწერა. ყველაფერი ზემოთ ჩამოთვლილი და მომხმარებლის ID-ების მიმაგრება identify ენდპოინტის მეშვეობით.

უფლებამოსილება გასაღების შექმნისას აირჩიეთ; ნაგულისხმევია მხოლოდ წაკითხვა. მხოლოდ წასაკითხი გასაღების გამოყენება ჩაწერის ენდპოინტზე აბრუნებს 403 შეტყობინებით, რომელშიც დასახელებულია გასაღების უფლებამოსილება და ენდპოინტის მოთხოვნა. უფლებამოსილების შემდგომი შეცვლა შეუძლებელია — შექმენით ახალი გასაღები და ძველი გააუქმეთ.

3. სიხშირის ლიმიტები

თითო API გასაღების ლიმიტია 60 მოთხოვნა წუთში, მოძრავი დროის ფანჯრით აღრიცხული. გადაჭარბებისას მოთხოვნები იღებს 429 პასუხს ფანჯრის გასუფთავებამდე:

{ "error": "Rate limit exceeded. Max 60 requests per minute." }

ქმნით რამეს, რასაც უფრო მაღალი ლიმიტი სჭირდება? დაგვიკავშირდით განყოფილებით მხარდაჭერა და თქვენი გამოყენების შემთხვევა გვიამბეთ.

4. ენდპოინტები

GET/api/v1/projects

ჩამოთვლის თქვენს სამუშაო სივრცეში ყველა პროექტს (აღრიცხულ საიტს).

{ "data": [ { "channelid": "955a45df5ee842cb", "domain": "yourdomain.com", "status": "active", "total_traffic_bytes": 27304765, "created_at": "2026-07-19 22:06:39", "last_used": "2026-08-05 01:12:55" } ] }

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

ჩამოთვლის პროექტისთვის ჩაწერილ ვიზიტორთა სესიებს, უახლესით დაწყებული. გვერდებად დაყოფილია.

მოთხოვნის პარამეტრი	აღწერა
`page`	გვერდის ნომერი, ნაგულისხმევად `1`.
`per_page`	შედეგები თითო გვერდზე, ნაგულისხმევად `25`, მაქსიმუმ `100`.
`since`	მხოლოდ ამ თარიღს ან მის შემდეგ დაწყებული სესიები (`YYYY-MM-DD`).
`until`	მხოლოდ ამ თარიღს ან მანამდე დაწყებული სესიები.

{ "data": [ { "session_id": "s_kfmist058_1785795295504", "visitor_id": "v_sv90jdpzo_1785795296042", "custom_user_id": null, "country": "DE", "device_type": "desktop", "is_bot": 0, "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105 } ], "pagination": { "page": 1, "per_page": 25, "total": 142, "total_pages": 6 } }

GET/api/v1/sessions/{session_id}

ერთი სესიის მეტამონაცემები და მისი გვერდის ნახვები. ხელახალი დაკვრის სრული მონაცემები განზრახ გამორიცხულია — ამისთვის დაფის პლეერი გამოიყენეთ.

{ "data": { "session_id": "s_kfmist058_1785795295504", "channelid": "955a45df5ee842cb", "visitor_id": "v_sv90jdpzo_1785795296042", "country": "DE", "asn_org": "Deutsche Telekom AG", "referrer": "https://duckduckgo.com/", "device_type": "desktop", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105, "pageviews": [ { "pageview_id": 1199, "url": "https://yourdomain.com/pricing", "page_title": "Pricing", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41" } ] } }

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

სესიის დროს ამოქმედებული მორგებული მოვლენები (იგივე მოვლენები, რომლებსაც აგზავნით ამ მეთოდით: mp('event', ...)), მათი პარამეტრების ჩათვლით.

{ "data": [ { "event_id": 61, "pageview_id": 1199, "event_name": "add_to_cart", "created_at": "2026-08-04 00:14:59", "params": { "item_id": "SKU_98765", "price": 299.99 } } ] }

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

ჩამოთვლის პროექტისთვის განსაზღვრულ ვიზიტორთა სეგმენტებს (როგორც პროექტის, ისე მთელი სამუშაო სივრცის სეგმენტებს).

{ "data": [ { "segment_id": 4, "name": "High Intent Visitors", "description": "Pageviews > 5", "badge_color": "cyan", "is_global": 0, "created_at": "2026-08-03 00:00:43" } ] }

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-მდე.

ერთი ID-ით ორჯერ გამოძახება უსაფრთხოა. პასუხი ბრუნდება ამ ველით: "changed": false და ვებჰუკი არ იგზავნება. განმეორებული შეკვეთა მეორე ლიდს არ ქმნის.

სტატუსი	როდის
`400`	ველი აკლია, `user_id` 128 სიმბოლოს აღემატება ან საკონტროლო სიმბოლოებს შეიცავს. შეკვეცის ნაცვლად უარვყოფთ — უხმოდ დამოკლებული ID თქვენს CRM-ში ვერაფერს დაემთხვევა და მაინც წარმატებას ჰგავს.
`404`	სესია არ არსებობს ან თქვენს სამუშაო სივრცეს არ ეკუთვნის. ორივე შემთხვევისთვის პასუხი განზრახ ერთნაირია.
`403`	სამუშაო სივრცის გეგმა API-ს არ მოიცავს.

6. ვებჰუკები: ხელმოწერის შემოწმება

ვებჰუკები თითო პროექტისთვის კონფიგურირდება განყოფილებაში ინტეგრაციები, სადაც ხელმოწერის საიდუმლოსაც იპოვით. ყოველ მიწოდებას ახლავს ეს სათაურები:

სათაური	მნიშვნელობა
`X-MousePlayer-Event`	მოვლენის სახელი, მაგალითად, `session_identified`
`X-MousePlayer-Timestamp`	Unix წამები — ხელმოწერილი ტექსტის ნაწილი
`X-MousePlayer-Attempt`	1 პირველი მცდელობისას, უფრო მაღალი ხელახალი მცდელობებისას
`X-MousePlayer-Signature`	`sha256=<hex>`

ხელმოწერა არის 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');

ხელი მოაწერეთ ნედლ სხეულს, JSON-ის გარჩევამდე. ხელახალი სერიალიზაცია გასაღებების მიმდევრობასა და გამოტოვებებს ცვლის და ხელმოწერა აღარასოდეს დაემთხვევა. ასევე უარყავით ყველაფერი, რომლის დროის ნიშნული რამდენიმე წუთზე ძველია — დროის ნიშნული სწორედ ამისთვისაა.

მიწოდება და ხელახალი მცდელობები

წარუმატებელი მიწოდება ხელახლა იცდება 1 წთ, 5 წთ, 15 წთ, 1 სთ და 6 სთშემდეგ, შემდეგ კი მცდელობები წყდება. 4xx პასუხები, გარდა 408 და 429 პასუხებისა, არ იგზავნება ხელახლა — ისინი ამბობენ "ასე არა" და არა "ახლა არა". სწრაფად უპასუხეთ 2xx და სამუშაო შემდეგ შეასრულეთ; მიწოდების დროის ლიმიტი 10 წამია.

ხელმისაწვდომი მოვლენები

მოვლენა	როდის ამოქმედდება
`session_identified`	როცა სესია პირველად მიიღებს მომხმარებლის ID-ს — ბრაუზერიდან ან API-დან
`session_ended`	ერთხელ, სესიის დახურვისას
`goal_reached`	ერთხელ თითო სესიაზე, როცა მორგებული მოვლენა თქვენს ერთ-ერთ მიზანს ასრულებს. მხოლოდ „მოვლენის“ ტიპის მიზნები — URL-ის, ხანგრძლივობის, გვერდის ნახვისა და ძაბრის მიზნები არ ფასდება. შეიცავს `goal_id`, `goal_name`, `goal_value` და `currency`.
`high_value_session`	როცა ვიზიტორი მოცემულ დღეს პირველად გადალახავს ამ პროექტის ღირებულების ზღვარს. ზღვარი თქვენი ქულების განაწილებიდან გამოითვლება (ბოლო 90 დღის 90-ე პროცენტილი) და არ არსებობს, სანამ სულ მცირე 20 ვიზიტორი არ შეფასდება. შეიცავს `visitor_id`, `value_score`, `threshold` და იმ დღის ყველაზე საყურებელ სესიას.
`funnel_dropoff`	იმ სესიის ბოლოს, რომელიც თქვენს ერთ-ერთ ძაბრში შევიდა, მაგრამ არ დაასრულა. ასახელებს ნაბიჯს, რომელზეც შეჩერდა (`dropped_at`). გამოთიშვა მოვლენის არარსებობაა, ამიტომ მხოლოდ სესიის დასრულების შემდეგ ვიგებთ მის შესახებ. სესიები, რომლებიც ძაბრში საერთოდ არ შესულა, გამოთიშვად არ ითვლება და მოვლენას არ ააქტიურებს.
`high_friction_session`	ერთხელ თითო სესიაზე, როცა დაბრკოლებების ქულა პირველად მიაღწევს ზღვარს (ნაგულისხმევად 60 ქულა 100-დან). შეიცავს `friction_score`, მის საფუძვლად არსებულ სიგნალებს (`reasons`) და სიგნალს, რომელმაც ზღვარი გადალახა (`trigger`).
`element_broken`	ერთხელ, როცა აღრიცხულ ელემენტს რამდენიმე დღის განმავლობაში არცერთ შემოწმებულ გვერდის ნახვაში არაფერი უპოვია — ჩვეულებრივ, ხელახალი გაშვების შემდეგ. ხელახლა მხოლოდ მაშინ ამოქმედდება, როცა მონიშვნა ჯერ დაემთხვევა და შემდეგ კვლავ დაირღვევა. ეს მოვლენა არ ეკუთვნის არცერთ სესიას: `session_id` და `session_url` არის `null`, `link_url` სანაცვლოდ მონიშვნას ხსნის, ხოლო `subject_id` ასახელებს მონიშვნას — ერთნაირად ყველა ვერსიისთვის, ამიტომ ახალი სელექტორის განმეორებითი დარღვევა ღია ინციდენტს უერთდება. შეიცავს `rule_id`, `rule_name`, `selector`, `page`, `checked_page_views`, `window_days` და `last_matched`. ვიზიტორის მონაცემების გარეშე.
`element_recovered`	ნორმაში დაბრუნების შეტყობინება ამ მოვლენისთვის: `element_broken`: ერთხელ, როცა მონიშვნა კვლავ ნამდვილად იპოვის ელემენტს — გვერდის ნახვების სიმცირე საკმარისი არ არის. იგზავნება მხოლოდ მაშინ, თუ `element_broken` ვებჰუკით გაიგზავნა, და საკუთარი ჩამრთველი არ აქვს: გამოწერა ამ მოვლენაზე `element_broken` მასაც მოიცავს. იგივე `subject_id`, ამიტომ PagerDuty ინციდენტს ხურავს, Opsgenie კი — გაფრთხილებას. დამატებით შეიცავს `matched_page_views` და `checked_page_views` .
`anomaly_detected`	დღეში ერთხელ, როცა გუშინდელი დღე წინა 28 დღისგან აშკარად განსხვავდება: გაცილებით ნაკლები ან მეტი სესია, მიზნის მიღწევის შემცირებული სიხშირე, მეტი სესია დაბრკოლებებით ან JS შეცდომებით. იგივე მეტრიკა და მიმართულება ერთი კვირით ჩუმდება (რეგულირებადია). ეს მოვლენა არ ეკუთვნის არცერთ სესიას: `session_id` და `session_url` არის `null`, `link_url` ხსნის პროექტის მიმოხილვას, ხოლო `subject_id` ასახელებს მეტრიკას, მიმართულებასა და დღეს. შეიცავს `metric` (`sessions`, `goal_rate`, `friction_rate`, `js_error_rate`, `lcp_p75`, `inp_p75`, `cls_p75`), `direction`, `day`, `value`, `expected`, `sessions`, `robust_z`, `z_score` და წაკითხვად `summary` და `hint`. ვიზიტორის მონაცემების გარეშე. Web Vitals-ისთვის, `measurements` ცვლის `sessions`, ხოლო `page` (ცარიელია მთელი საიტისთვის) და `device` (`desktop` ან `mobil`) აჩვენებს, სად მოხდა; `link_url` შემდეგ Web Vitals ჩანართს ხსნის.
`rage_click`	აღმოჩენილი გაბრაზებული დაწკაპუნებისას
`error_detected`	ფრონტენდის გამონაკლისისას
`ce`	საერთო გამოწერა თქვენს მორგებულ მოვლენებზე. ის არ მოიცავს ზემოთ ჩამოთვლილ მოვლენებს — მათ საკუთარი ჩამრთველები აქვს.

7. შეცდომები & სტატუსის კოდები

სტატუსი	მნიშვნელობა
`200`	წარმატება.
`401`	დაკარგული, არასწორი ფორმატის ან გაუქმებული API გასაღები.
`404`	მოთხოვნილი პროექტი ან სესია არ არსებობს ან თქვენს სამუშაო სივრცეს არ ეკუთვნის.
`429`	სიხშირის ლიმიტი გადაჭარბებულია — ამ გასაღებით წუთში 60-ზე მეტ მოთხოვნას აგზავნით.
`403`	სამუშაო სივრცის გეგმა REST API-ს არ მოიცავს. შეტყობინება ასახელებს როგორც საჭირო, ისე მიმდინარე გეგმას.

8. უსაფრთხოების შენიშვნები

მხოლოდ წასაკითხი გასაღებები (mp_ro_) ვერაფერს ცვლის. ჩაწერის გასაღებებს (mp_rw_) მხოლოდ მომხმარებლის ID-ების მიმაგრება შეუძლია; არცერთ გასაღებს მონაცემების წაშლა ან ხელახალი დაკვრის ნედლი მონაცემების ექსპორტი არ შეუძლია.
ყოველი მოთხოვნა ავტომატურად გასაღების საკუთარ სამუშაო სივრცეს მიეკუთვნება — სხვა სამუშაო სივრცის ID-ის გადაცემა და სხვისი მონაცემების ნახვა შეუძლებელია.
გასაღები ნებისმიერ დროს გააუქმეთ აქ: /api-keys; გაუქმება დაუყოვნებლივ მოქმედებს.
API გასაღებს პაროლივით მოეპყარით. თუ შემთხვევით საჯარო რეპოზიტორიაში დააკომიტებთ, დაუყოვნებლივ გააუქმეთ და ახალი შექმენით.

მოვლენების შეზღუდული გვერდები (API v1, 14 ოქტომბერი 2026)

GET /api/v1/sessions/{session_id}/events ნაგულისხმევად მაქსიმუმ 100 მოვლენას აბრუნებს. per_page-ისთვის მიუთითეთ მთელი რიცხვი 1-დან 100-მდე. pagination.next_cursor-ს მიჰყევით: მომდევნო მოთხოვნაში cursor უცვლელად გაგზავნეთ; იგივე სესია და სამუშაო სივრცე შეინარჩუნეთ. მოვლენები created_at-ისა და event_id-ის მიხედვით ლაგდება. კურსორები ხელმოწერილია და ამ სესიასა და სამუშაო სივრცეს უკავშირდება. საერთო რაოდენობა ან რიცხვითი გვერდი არ ბრუნდება.

არსებული data მასივი და params რუკა ხელმისაწვდომი რჩება. pagination.returned დაბრუნებულთა ფაქტობრივი რაოდენობაა; pagination.has_more სხვა გვერდის არსებობას აღნიშნავს. დასრულებისას next_cursor არის null. პასუხი მაქსიმუმ 524288 ბაიტია, ამიტომ გვერდში შეიძლება per_page-ზე ნაკლები მოვლენა იყოს. თითო მოვლენაზე მაქსიმუმ 128 პარამეტრის მწკრივი ბრუნდება; მეტის არსებობისას params_truncated არის true. ცალკეული სტრიქონული პარამეტრები ინარჩუნებს მონაცემთა ბაზის 255 სიმბოლოს ლიმიტს. შეკვეცილი პარამეტრები ამ ენდპოინტით ხელმისაწვდომი არ არის. per_page-ის შემცირება პარამეტრების ლიმიტს არ ზრდის.

გვერდის არასწორი ზომები, შეცვლილი კურსორები და სხვა სესიის/სამუშაო სივრცის კურსორები აბრუნებს 400-ს. ცალკეული მოვლენის ზედმეტად დიდი მონაცემები აბრუნებს 413-ს. წვდომის არსებული შემოწმებები კვლავ აბრუნებს 401-ს, 403-ს, 404-ს ან 409-ს, შესაბამისი შემთხვევის მიხედვით.

ლიმიტი კვლავ წუთში 60 ავთენტიფიცირებული მოთხოვნაა თითო API გასაღებზე. ამოწურვისას ბრუნდება 429 სათაურით Retry-After: 60. თუ Redis ან ლიმიტერი მიუწვდომელია, მოთხოვნები აბრუნებს 503-ს სათაურით Retry-After: 5; ლიმიტის გარეშე ისინი არასოდეს დაიშვება. დაიცავით Retry-After და დაამატეთ შემთხვევითი დაყოვნება; სწრაფ ციკლში ხელახლა ნუ სცდით. მოვლენების მონაცემთა ბაზის შეცდომებიც 503-ს აბრუნებს. კურსორები გვერდის სურათს არ აფიქსირებს: ძველი დროის ნიშნულებით პარალელურ ჩასმებს შეიძლება ახალი სრული წაკითხვა დასჭირდეს.

GET /api/v1/sessions/s_example/events?per_page=25
GET /api/v1/sessions/s_example/events?per_page=25&cursor=SIGNED_CURSOR

/api/v1/native ნატიური SDK-ის წინასწარი ხედისთვის მხოლოდ Dev ბექენდის საკონტროლო მარშრუტია. წარმოებაში ის გამორთული რჩება. ბექენდის Bearer გასაღებებს სიისთვის/ხელახალი დაკვრისთვის წაკითხვის უფლებამოსილება სჭირდება, რეგისტრაციისთვის/დაშვებისთვის/წაშლისთვის/გამორთვისთვის კი — ჩაწერის. მოქმედებს ნატიური წინასწარი ხედის ხელმისაწვდომობის დამატებითი შემოწმებები. მობილურ აპში მუდმივი სამუშაო სივრცის API გასაღებები არასოდეს ჩააშენოთ.

როგორ შეგვიძლია დაგეხმაროთ?