सार्वजनिक API आणि API की

1. आढावा

API ने डेटा डॅशबोर्ड, वेअरहाउस किंवा अंतर्गत साधनांत आणा. सत्राला ग्राहक ID जोडणे वगळता (identify; लेखन व्याप्तीची की आवश्यक, की व्याप्ती पाहा) हा केवळ वाचनाचा: डेटा बदलता किंवा हटवता येत नाही.

मूळ URL: https://www.mouseplayer.com/api/v1/
सर्व उत्तरे JSON.
प्रत्येक विनंती कीने प्रमाणित आणि तिच्या कार्यक्षेत्रापुरती — दुसऱ्या कार्यक्षेत्राचा डेटा चुकूनही दिसत नाही.
पूर्ण सत्र रेकॉर्डिंग (माऊस, DOM स्नॅपशॉट) API वर उपलब्ध नाही . मेटाडेटा, पृष्ठदृश्ये, घटना आणि विभाग मिळतात — कच्चा पुनर्प्ले डेटा न हलवता अहवालांसाठी पुरेसे.

2. प्रमाणीकरण

खाते मेनूमधील पुढील विभागात की बनवा व व्यवस्थापित करा: 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_`	वाचन आणि लेखन. वरील सर्व; identify ने ग्राहक ID जोडणेही.

की बनवताना व्याप्ती निवडा; डीफॉल्ट वाचन. लेखन एंडपॉइंटवर वाचन कीला: 403 आणि आवश्यक व्याप्ती सांगणारा संदेश. नंतर बदलता येत नाही — नवीन बनवा, जुनी रद्द करा.

3. दर मर्यादा

प्रत्येक कीसाठी कमाल मिनिटाला 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 webhook चालतो — त्याने CRM पर्यंत पोहोचते.

तोच ID दोनदा देणे सुरक्षित. उत्तरात पुढील येते: "changed": false ; webhook नाही. पुन्हा दिलेल्या ऑर्डरचा दुसरा लीड बनत नाही.

स्थिती	केव्हा
`400`	फील्ड नाही, `user_id` 128 अक्षरांपेक्षा मोठे किंवा नियंत्रण अक्षरे. कापण्याऐवजी नाकारतो — छोटा ID CRM ला जुळणार नाही, पण यश वाटेल.
`404`	सत्र अस्तित्वात नाही किंवा कार्यक्षेत्राचे नाही. मुद्दाम दोन्हीला तेच उत्तर.
`403`	योजनेत API नाही.

6. Webhook स्वाक्षरी पडताळणी

प्रत्येक प्रकल्पात पुढीलखाली सेट करा: एकत्रीकरणे; स्वाक्षरी सीक्रेटही तिथे. प्रत्येक वितरणात हेडर:

हेडर	अर्थ
`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`	सानुकूल घटनेने उद्दिष्ट पूर्ण केल्यावर सत्रात एकदा. फक्त “event” प्रकारची उद्दिष्टे — 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` webhook ने गेले असेल तर; स्वतंत्र स्विच नाही. पुढीलची सदस्यता: `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`	की नाही, चुकीची किंवा रद्द.
`404`	प्रकल्प/सत्र नाही किंवा कार्यक्षेत्राचे नाही.
`429`	दरमर्यादा ओलांडली — या कीने मिनिटाला 60 पेक्षा जास्त विनंत्या.
`403`	योजनेत REST API नाही. संदेशात आवश्यक आणि सध्याची योजना.

8. सुरक्षा टिपा

वाचन की (mp_ro_) बदल करू शकत नाहीत. लेखन की (mp_rw_) फक्त ग्राहक ID जोडतात; डेटा हटवणे किंवा कच्चा पुनर्प्ले निर्यात कोणत्याही कीने नाही.
प्रत्येक विनंती कीच्या कार्यक्षेत्रापुरती — वेगळा कार्यक्षेत्र ID देऊन इतरांचा डेटा पाहता येत नाही.
पुढीलमधून कधीही की रद्द करा: /api-keys; त्वरित लागू.
की पासवर्डसारखी ठेवा. सार्वजनिक रिपॉझिटरीत चुकून कमिट झाल्यास लगेच रद्द करून नवीन बनवा.

मर्यादित घटना पृष्ठे (API v1, 14 ऑक्टोबर 2026)

GET /api/v1/sessions/{session_id}/events डीफॉल्टने 100 पर्यंत घटना देते. per_page पूर्णांक 1 ते 100 द्या. पुढील विनंतीत cursor न बदलता पाठवून pagination.next_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 प्रमाणित विनंत्यांची मर्यादा कायम. संपल्यास 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 कीला list/replay साठी वाचन, register/grant/delete/disable साठी लेखन व्याप्ती. अतिरिक्त उपलब्धता तपासण्या लागू. कायम कार्यक्षेत्र API की मोबाइल अॅपमध्ये कधीही ठेवू नका.

आम्ही कशी मदत करू शकतो?