బహిరంగ 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 :
లేని, తప్పు ఆకృతిలో ఉన్న లేదా రద్దు చేసిన కీలకు వచ్చే స్పందన 401 :
ప్లాన్ అవసరం
REST API భాగంగా ఉండే ప్లాన్‌లు Business మరియు Enterprise . ప్లాన్ తీసుకునే ఆధారం వర్క్‌స్పేస్ యజమాని కాబట్టి ఆహ్వానిత బృంద సభ్యులకూ అదే వర్తిస్తుంది. తనిఖీ జరిగేది ప్రతి అభ్యర్థనపై, కీ సృష్టించినప్పుడు మాత్రమే కాదు — వర్క్‌స్పేస్ దిగువ స్థాయికి మారితే ఉన్న కీలు ఆగి, ఇచ్చే స్పందన 403.
కీ పరిధులు
ప్రతి కీ దాని ఉపసర్గలోనే పరిధిని కలిగి ఉంటుంది కాబట్టి చూడగానే దాని పని తెలుసుకోవచ్చు — ఇందులోనైనా .env, టికెట్‌లోనైనా, టెర్మినల్‌లోనైనా.
| ఉపసర్గ | అర్థం |
|---|---|
mp_ro_ | చదవడానికి మాత్రమే. ప్రాజెక్ట్‌లు, సెషన్‌లు, ఈవెంట్‌లు, సెగ్మెంట్‌లను చదువుతుంది. ఏదీ మార్చలేదు. |
mp_rw_ | చదవడం, రాయడం. పైన ఉన్నవన్నీ, అదనంగా identify ఎండ్‌పాయింట్ ద్వారా కస్టమర్ IDలు జోడించడం. |
403 , కీ రకం, ఎండ్‌పాయింట్ అవసరాన్ని తెలిపే సందేశంతో. తర్వాత పరిధిని మార్చలేరు — కొత్త కీ సృష్టించి పాతది రద్దు చేయండి.3. అభ్యర్థన రేటు పరిమితులు
ప్రతి API కీకి పరిమితి నిమిషానికి 60 అభ్యర్థనలు, కదిలే కాలవ్యవధిలో లెక్కించబడతాయి. దాటితే అభ్యర్థనలకు వచ్చే స్పందన 429 ; కాలవ్యవధి ఖాళీ అయ్యే వరకు:
అధిక పరిమితి అవసరమైనది నిర్మిస్తున్నారా? ఈ మార్గంలో సంప్రదించండి: సహాయం ; మీ వినియోగ సందర్భాన్ని తెలియజేయండి.
4. ఎండ్‌పాయింట్‌లు
GET/api/v1/projects
మీ వర్క్‌స్పేస్‌లో ప్రతి ప్రాజెక్ట్‌ను (ట్రాక్ చేసే సైట్‌ను) జాబితా చేస్తుంది.
GET/api/v1/projects/{channelid}/sessions
ప్రాజెక్ట్‌కు రికార్డ్ చేసిన సందర్శక సెషన్‌లను సరికొత్తవి ముందుగా జాబితా చేస్తుంది. పేజీలుగా విభజించబడుతుంది.
| క్వెరీ పారామీటర్ | వివరణ |
|---|---|
page | పేజీ సంఖ్య, డిఫాల్ట్ 1. |
per_page | ఒక్కో పేజీకి ఫలితాలు, డిఫాల్ట్ 25, గరిష్ఠం 100. |
since | ఈ తేదీన లేదా తర్వాత ప్రారంభమైన సెషన్‌లు మాత్రమే (YYYY-MM-DD). |
until | ఈ తేదీన లేదా ముందు ప్రారంభమైన సెషన్‌లు మాత్రమే. |
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కు చేరుతుంది.
"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');
పంపిణీ, పునఃప్రయత్నాలు
విఫల పంపిణీ తర్వాత మళ్లీ ప్రయత్నించే విరామాలు 1 నిమి, 5 నిమి, 15 నిమి, 1 గం, 6 గం; తర్వాత వదిలేస్తాము. 4xx ఈ స్పందనల్లో, ఇవి మినహా 408 మరియు 429 , మళ్లీ ప్రయత్నించడం లేదు — అవి "ఇలా కాదు" అని చెబుతాయి, "ఇప్పుడు కాదు" అని కాదు. వెంటనే ఈ స్పందన ఇచ్చి 2xx , పని తర్వాత చేయండి; పంపిణీ 10 సెకన్ల తర్వాత గడువు ముగుస్తుంది.
అందుబాటులో ఉన్న ఈవెంట్‌లు
| ఈవెంట్ | ప్రారంభమయ్యే సందర్భం |
|---|---|
session_identified | బ్రౌజర్ లేదా API నుంచి సెషన్‌కు మొదటిసారి కస్టమర్ ID వచ్చినప్పుడు — |
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 వెబ్‌హుక్ ద్వారా వెళ్లి ఉండాలి; దీనికి స్వంత స్విచ్ లేదు. దీన్ని సబ్‌స్క్రైబ్ చేస్తే 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 మధ్య పూర్ణసంఖ్యగా సెట్ చేయండి. తదుపరి అభ్యర్థనలో 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 ఇస్తూనే ఉంటాయి.
పరిమితి ఒక్కో API కీకి నిమిషానికి 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కు మాత్రమే చెందిన బ్యాక్‌ఎండ్ నియంత్రణ మార్గం. ప్రొడక్షన్‌లో నిలిపివేయబడుతుంది. Backend Bearer కీలకు list/replay కోసం రీడ్ పరిధి, register/grant/delete/disable కోసం రాత పరిధి అవసరం. అదనపు native-preview అందుబాటు తనిఖీలు వర్తిస్తాయి. శాశ్వత వర్క్‌స్పేస్ API కీలను మొబైల్ యాప్‌లో ఎప్పుడూ చేర్చవద్దు.