ይፋዊ 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 | ክፍለ ጊዜ መጀመሪያ የደንበኛ 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 በዌብሁክ ከወጣ ብቻ ነው፣ የራሱም ማብሪያ የለውም፦ ለ 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-ብቻ የኋላ ጫፍ መቆጣጠሪያ መንገድ ነው። በምርት አካባቢ ተሰናክሎ ይቆያል። የኋላ ጫፍ Bearer ቁልፎች ለlist/replay የንባብ ወሰን፣ ለregister/grant/delete/disable የመጻፍ ወሰን ይፈልጋሉ። ተጨማሪ የተወላጅ ቅድመ እይታ ተገኝነት ፍተሻዎች ይተገበራሉ። ቋሚ የስራ ቦታ የAPI ቁልፎችን በሞባይል መተግበሪያ ውስጥ ፈጽሞ አያካትቱ።