API ציבורי ומפתחות API

1. סקירה כללית

API ה-MousePlayer מאפשר למשוך נתונים מסביבת העבודה ללוחות מחוונים, למחסן נתונים או לכלים פנימיים משלך. מלבד צירוף מזהי לקוחות לסשנים (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>" }

דרישת תוכנית

API ה-REST נכלל בתוכניות Business וכן Enterprise — התוכנית נקבעת לפי הבעלים של סביבת העבודה, ולכן חברי צוות מוזמנים יורשים אותה. הבדיקה מתבצעת בכל בקשה, ולא רק ביצירת מפתח — אם סביבת עבודה משונמכת, מפתחות קיימים מפסיקים לפעול ומחזירים 403.

הרשאות מפתח

כל מפתח נושא את ההרשאה בקידומת שלו, כך שניתן לדעת מה הוא עושה מעצם ההסתכלות עליו — בקובץ .env, בפנייה או במסוף.

קידומת	משמעות
`mp_ro_`	קריאה בלבד. קורא פרויקטים, סשנים, אירועים ופלחים. אינו יכול לשנות דבר.
`mp_rw_`	קריאה וכתיבה. כל האמור למעלה, ובנוסף צירוף מזהי לקוחות דרך נקודת הקצה 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. צירוף מזהה לקוח מהשרת שלך

לעיתים הדפדפן אינו יודע מי נמצא בו. במוצר 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}}

המזהה מופיע אז ברשימת הסשנים וניתן לחיפוש בה, ומופעל ה-Webhook session_identified — כך הוא מגיע ל-CRM שלך.

קריאה פעמיים עם אותו מזהה בטוחה. התשובה חוזרת עם "changed": false ולא נשלח Webhook. הזמנה חוזרת אינה יוצרת ליד נוסף.

סטטוס	מתי
`400`	שדה חסר, `user_id` ארוך מ-128 תווים או כולל תווי בקרה. אנו דוחים במקום לחתוך — מזהה שקוצר בשקט לא יתאים לדבר ב-CRM ועדיין ייראה כהצלחה.
`404`	הסשן אינו קיים או אינו שייך לסביבת העבודה. במכוון זו אותה תשובה לשניהם.
`403`	תוכנית סביבת העבודה אינה כוללת את ה-API.

6. Webhooks: אימות חתימה

Webhooks מוגדרים לכל פרויקט תחת שילובים, ושם נמצא גם סוד החתימה. כל משלוח כולל כותרות אלה:

כותרת	משמעות
`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`	כשסשן מקבל לראשונה מזהה לקוח — מהדפדפן או מה-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` נשלח דרך 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`	מפתח API חסר, פגום או מבוטל.
`404`	הפרויקט או הסשן המבוקש אינם קיימים או אינם שייכים לסביבת העבודה.
`429`	חריגה ממגבלת הקצב — נשלחות יותר מ-60 בקשות לדקה עם מפתח זה.
`403`	תוכנית סביבת העבודה אינה כוללת את API ה-REST. ההודעה מציינת הן את התוכנית הדרושה והן את הנוכחית.

8. הערות אבטחה

מפתחות לקריאה בלבד (mp_ro_) אינם יכולים לשנות דבר. מפתחות כתיבה (mp_rw_) יכולים רק לצרף מזהי לקוחות; אף מפתח אינו יכול למחוק נתונים או לייצא נתוני הקלטה גולמיים.
כל בקשה מוגבלת אוטומטית לסביבת העבודה של המפתח — אין דרך להעביר מזהה של סביבה אחרת ולראות נתונים של מישהו אחר.
ניתן לבטל מפתח בכל עת דרך /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 הוא נתיב בקרה בשרת המיועד ל-Dev בלבד, לתצוגה המקדימה של SDK מקורי. הוא נשאר מושבת בסביבת הייצור. מפתחות Bearer בשרת דורשים הרשאת קריאה עבור list/replay והרשאת כתיבה עבור register/grant/delete/disable. חלות בדיקות זמינות נוספות לתצוגה המקדימה המקורית. לעולם אין להטמיע מפתחות API קבועים של סביבת עבודה באפליקציה ניידת.

איך אפשר לעזור?