Δημόσιο API & κλειδιά API

1. Επισκόπηση

Το API του MousePlayer σάς επιτρέπει να ανακτάτε δεδομένα από τον χώρο εργασίας σας στους δικούς σας πίνακες ελέγχου, στην αποθήκη δεδομένων ή στα εσωτερικά εργαλεία σας. Εκτός από τη σύνδεση ID πελατών με συνεδρίες (identify, απαιτεί κλειδί με δικαίωμα εγγραφής, δείτε Εμβέλεια κλειδιών), παρέχει μόνο ανάγνωση: κανένα δεδομένο δεν μπορεί να τροποποιηθεί ή να διαγραφεί μέσω του API.

• Βασικό URL: https://www.mouseplayer.com/api/v1/
• Όλες οι αποκρίσεις είναι JSON.
• Κάθε αίτημα ελέγχεται με κλειδί API και περιορίζεται αυτόματα στον χώρο εργασίας στον οποίο ανήκει το κλειδί — ένα κλειδί από έναν χώρο εργασίας δεν μπορεί ποτέ να δει δεδομένα άλλου χώρου, ούτε κατά λάθος.
• Η πλήρης καταγραφή αναπαραγωγής συνεδρίας (κινήσεις ποντικιού, στιγμιότυπα DOM) δεν διατίθεται μέσω του API. Λαμβάνετε μεταδεδομένα συνεδριών, προβολές σελίδας, προσαρμοσμένα συμβάντα και τμήματα — αρκετά για τη δημιουργία αναφορών και πινάκων ελέγχου χωρίς μεταφορά του ανεπεξέργαστου φορτίου αναπαραγωγής.

2. Έλεγχος ταυτότητας

Δημιουργήστε και διαχειριστείτε τα κλειδιά API στην ενότητα Κλειδιά API του μενού λογαριασμού σας (/api-keys). Μόνο κάτοχοι και διαχειριστές χώρου εργασίας μπορούν να δημιουργούν ή να ανακαλούν κλειδιά.

Στείλτε το κλειδί ως token Bearer στην κεφαλίδα Authorization κάθε αιτήματος:

Κλειδιά που λείπουν, έχουν λανθασμένη μορφή ή έχουν ανακληθεί λαμβάνουν απόκριση 401:

Απαίτηση προγράμματος

Το REST API περιλαμβάνεται στα προγράμματα Business και Enterprise. Λαμβάνεται υπόψη το πρόγραμμα του κατόχου του χώρου εργασίας, οπότε τα προσκεκλημένα μέλη ομάδας το κληρονομούν. Ο έλεγχος εκτελείται σε κάθε αίτημα, όχι μόνο όταν δημιουργείται ένα κλειδί — αν υποβαθμιστεί ο χώρος εργασίας, τα υπάρχοντα κλειδιά παύουν να λειτουργούν και επιστρέφουν 403.

Εμβέλεια κλειδιών

Κάθε κλειδί δηλώνει την εμβέλειά του στο δικό του πρόθεμα, ώστε να μπορείτε να καταλάβετε τι κάνει απλώς κοιτάζοντάς το — σε ένα .env, σε ένα αίτημα, σε ένα τερματικό.

3. Όρια ρυθμού αιτημάτων

Κάθε κλειδί API περιορίζεται σε 60 αιτήματα ανά λεπτό, με παρακολούθηση σε κυλιόμενο χρονικό παράθυρο. Μόλις το υπερβείτε, τα αιτήματα λαμβάνουν απόκριση 429 μέχρι να εκκαθαριστεί το παράθυρο:

4. Τελικά σημεία

GET/api/v1/projects

Παραθέτει κάθε έργο (παρακολουθούμενο ιστότοπο) στον χώρο εργασίας σας.

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

Παραθέτει τις συνεδρίες επισκεπτών που καταγράφηκαν για ένα έργο, με τις νεότερες πρώτα. Με σελιδοποίηση.

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 εμφανίζεται έπειτα στη λίστα συνεδριών, μπορεί να αναζητηθεί εκεί και ενεργοποιείται το webhook session_identified — έτσι φτάνει στο CRM σας.

6. Webhook: επαλήθευση της υπογραφής

Τα webhook διαμορφώνονται ανά έργο στην ενότητα Ενσωματώσεις, όπου βρίσκετε και το μυστικό υπογραφής. Κάθε παράδοση περιέχει αυτές τις κεφαλίδες:

Η υπογραφή είναι 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 δευτερόλεπτα.

Διαθέσιμα συμβάντα

7. Σφάλματα & κωδικοί κατάστασης

8. Σημειώσεις ασφαλείας

• Τα κλειδιά μόνο ανάγνωσης (mp_ro_) δεν μπορούν να αλλάξουν τίποτα. Τα κλειδιά εγγραφής (mp_rw_) μπορούν μόνο να συνδέουν ID πελατών· κανένα κλειδί δεν μπορεί να διαγράψει δεδομένα ή να εξαγάγει ανεπεξέργαστα δεδομένα αναπαραγωγής.
• Κάθε αίτημα περιορίζεται αυτόματα στον χώρο εργασίας του ίδιου του κλειδιού — δεν υπάρχει τρόπος να μεταβιβάσετε διαφορετικό ID χώρου εργασίας και να δείτε δεδομένα άλλου.
• Ανακαλέστε ένα κλειδί ανά πάσα στιγμή από το /api-keys· η ανάκληση τίθεται σε ισχύ αμέσως.
• Αντιμετωπίζετε το κλειδί API σας όπως έναν κωδικό πρόσβασης. Αν κατά λάθος το καταχωρίσετε σε δημόσιο αποθετήριο, ανακαλέστε το αμέσως και δημιουργήστε νέο.