API Awam & Kunci API
Akses secara pengaturcaraan ke ruang kerja anda — baca projek, sesi, peristiwa tersuai dan segmen, serta lampirkan ID pelanggan pada sesi — dilindungi oleh kunci API berskop ruang kerja.
1. Gambaran keseluruhan
API MousePlayer membolehkan anda mengambil data daripada ruang kerja ke papan pemuka, gudang data atau alat dalaman sendiri. Selain melampirkan ID pelanggan pada sesi (identify, memerlukan kunci dengan skop tulis, lihat Skop kunci), ia baca sahaja: tiada data boleh diubah atau dipadamkan melalui API.
- URL asas:
https://www.mouseplayer.com/api/v1/ - Semua respons ialah JSON.
- Setiap permintaan disahkan dengan kunci API dan diskopkan secara automatik kepada ruang kerja pemilik kunci itu — kunci satu ruang kerja tidak pernah boleh melihat data ruang kerja lain, walaupun secara tidak sengaja.
- Rakaman main semula sesi penuh (pergerakan tetikus, petikan DOM) tidak didedahkan melalui API. Anda mendapat metadata sesi, paparan halaman, peristiwa tersuai dan segmen — cukup untuk membina laporan dan papan pemuka tanpa menghantar muatan main semula mentah ke tempat lain.
2. Pengesahan
Cipta dan urus kunci API anda di Kunci API dalam menu akaun (/api-keys). Hanya pemilik dan pentadbir ruang kerja boleh mencipta atau membatalkan kunci.
Rahsiakan kunci anda. Ia memberikan akses baca kepada segala-galanya dalam ruang kerja anda. Kunci penuh ditunjukkan tepat sekali, sejurus dicipta — simpan dalam pengurus kata laluan atau peti rahsia. Jika hilang, batalkan dan cipta yang baharu.
Hantar kunci sebagai token Bearer dalam pengepala Authorization setiap permintaan:
Kunci yang tiada, salah bentuk atau dibatalkan menerima respons 401 :
Keperluan pelan
REST API sebahagian daripada pelan Business dan Enterprise . Pelan diambil daripada pemilik ruang kerja, jadi ahli pasukan dijemput mewarisinya. Semakan berjalan pada setiap permintaan, bukan hanya ketika kunci dicipta — jika ruang kerja diturunkan taraf, kunci sedia ada berhenti berfungsi dan mengembalikan 403.
Skop kunci
Setiap kunci membawa skop dalam awalannya sendiri, jadi anda boleh mengetahui fungsinya hanya dengan melihat — dalam .env, tiket atau terminal.
| Awalan | Maksud |
|---|---|
mp_ro_ | Baca sahaja. Membaca projek, sesi, peristiwa dan segmen. Tidak boleh mengubah apa-apa. |
mp_rw_ | Baca dan tulis. Semua di atas, serta melampirkan ID pelanggan melalui titik akhir identify. |
403 dengan mesej yang menyatakan jenis kunci dan keperluan titik akhir. Skop tidak boleh diubah kemudian — cipta kunci baharu dan batalkan yang lama.3. Had kadar
Setiap kunci API dihadkan kepada 60 permintaan seminit, dijejak pada jendela bergerak. Setelah melebihi had, permintaan menerima respons 429 sehingga jendela berakhir:
Membina sesuatu yang memerlukan had lebih tinggi? Hubungi melalui Sokongan dan beritahu kes penggunaan anda.
4. Titik akhir
GET/api/v1/projects
Menyenaraikan setiap projek (aset web dijejak) dalam ruang kerja anda.
GET/api/v1/projects/{channelid}/sessions
Menyenaraikan sesi pelawat dirakam untuk projek, terbaharu dahulu. Berhalaman.
| Parameter pertanyaan | Huraian |
|---|---|
page | Nombor halaman, lalai 1. |
per_page | Hasil setiap halaman, lalai 25, maksimum 100. |
since | Hanya sesi yang bermula pada/selepas tarikh ini (YYYY-MM-DD). |
until | Hanya sesi yang bermula pada/sebelum tarikh ini. |
GET/api/v1/sessions/{session_id}
Metadata satu sesi, serta paparan halamannya. Sengaja mengecualikan muatan main semula penuh — gunakan Pemain papan pemuka untuk itu.
GET/api/v1/sessions/{session_id}/events
Peristiwa tersuai dicetuskan semasa sesi (peristiwa sama yang anda hantar dengan mp('event', ...)), termasuk parameternya.
GET/api/v1/projects/{channelid}/segments
Menyenaraikan segmen pelawat ditakrifkan untuk projek (segmen khusus projek dan merentas ruang kerja).
5. Melampirkan ID pelanggan daripada bahagian belakang anda
Pelayar sering tidak mengetahui siapa di situ. Dalam produk B2B, identiti ditentukan selepas daftar masuk — dalam bahagian belakang anda. Dalam kedai, ia ditentukan bersama pengesahan pesanan. Titik akhir ini untuk saat itu tepat-tepat.
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 kemudian muncul dalam senarai sesi, boleh dicari di situ, dan webhook session_identified dicetuskan — begitulah ia mencapai CRM anda.
"changed": false dan tiada webhook dihantar. Pesanan berulang tidak mencipta prospek kedua.| Status | Masa |
|---|---|
400 | Medan tiada, user_id melebihi 128 aksara, atau mengandungi aksara kawalan. Kami menolak, bukan memotong — ID dipendekkan secara senyap tidak sepadan dengan apa-apa dalam CRM dan masih kelihatan berjaya. |
404 | Sesi tidak wujud atau tidak tergolong dalam ruang kerja anda. Sengaja memberikan jawapan sama untuk kedua-duanya. |
403 | Pelan ruang kerja tidak merangkumi API. |
6. Webhook: mengesahkan tandatangan
Webhook dikonfigurasi bagi setiap projek di Integrasi, tempat anda turut menemui rahsia tandatangan. Setiap penghantaran membawa pengepala ini:
| Pengepala | Maksud |
|---|---|
X-MousePlayer-Event | Nama peristiwa, cth. session_identified |
X-MousePlayer-Timestamp | Saat Unix — sebahagian teks bertandatangan |
X-MousePlayer-Attempt | 1 pada percubaan pertama, lebih tinggi pada percubaan semula |
X-MousePlayer-Signature | sha256=<hex> |
Tandatangan ialah HMAC-SHA256 terhadap timestamp + "." + raw body, menggunakan rahsia tandatangan projek anda sebagai kunci.
// 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');
Penghantaran dan percubaan semula
Penghantaran gagal dicuba semula selepas 1 min, 5 min, 15 min, 1 jam dan 6 jam, kemudian dihentikan. 4xx Respons selain 408 dan 429 tidak dicuba semula — ia menyatakan "bukan begini", bukan "bukan sekarang". Balas 2xx dengan pantas dan lakukan kerja selepas itu; penghantaran tamat masa selepas 10 saat.
Peristiwa tersedia
| Peristiwa | Dicetuskan |
|---|---|
session_identified | Apabila sesi mendapat ID pelanggan buat kali pertama — daripada pelayar atau API |
session_ended | Sekali, apabila sesi ditutup |
goal_reached | Sekali setiap sesi, apabila peristiwa tersuai memenuhi salah satu matlamat anda. Hanya matlamat jenis “event” — matlamat URL, tempoh, paparan halaman dan corong tidak dinilai. Membawa goal_id, goal_name, goal_value dan currency. |
high_value_session | Apabila pelawat melintasi ambang nilai projek ini buat kali pertama pada sesuatu hari. Ambang diperoleh daripada taburan skor anda sendiri (persentil ke-90 dalam 90 hari terakhir), bukan nombor tetap, dan tidak wujud sehingga sekurang-kurangnya 20 pelawat diberikan skor. Membawa visitor_id, value_score, threshold dan sesi paling berbaloi ditonton pada hari itu. |
funnel_dropoff | Pada akhir sesi yang memasuki salah satu corong anda tetapi tidak menyelesaikannya. Menamakan langkah tempat ia berhenti (dropped_at). Penghentian ialah ketiadaan peristiwa, jadi hanya diketahui apabila sesi berakhir. Sesi yang tidak pernah memasuki corong bukan penghentian dan tidak mencetuskan peristiwa. |
high_friction_session | Sekali setiap sesi, apabila skor geserannya mencapai ambang buat kali pertama (lalai 60 daripada 100). Membawa friction_score, isyarat di sebaliknya (reasons) dan isyarat yang melintasi ambang (trigger). |
element_broken | Sekali, apabila elemen dijejak tidak menemui apa-apa dalam mana-mana paparan halaman diperiksa selama beberapa hari — biasanya selepas pelancaran semula. Dicetuskan lagi hanya selepas penandaan sepadan lalu rosak sekali lagi. Peristiwa ini tidak tergolong pada sebarang sesi: session_id dan session_url ialah null, link_url sebaliknya membuka penandaan, dan subject_id menamakan penandaan — sama untuk setiap versi, jadi pemilih baharu yang rosak semula menyertai insiden terbuka. Membawa rule_id, rule_name, selector, page, checked_page_views, window_days dan last_matched. Tiada data pelawat. |
element_recovered | Isyarat pulih untuk element_broken: sekali apabila penandaan benar-benar menemui elemen semula — paparan halaman terlalu sedikit tidak mencukupi. Hanya dihantar jika element_broken telah dihantar melalui webhook, dan ia tiada suis sendiri: melanggan element_broken turut merangkuminya. Nilai sama bagi subject_id, jadi PagerDuty menyelesaikan insiden dan Opsgenie menutup amaran. Membawa matched_page_views dan checked_page_views sebagai tambahan. |
anomaly_detected | Sekali sehari, apabila semalam jelas berbeza daripada 28 hari sebelumnya: sesi jauh lebih sedikit atau banyak, kadar matlamat menurun, lebih banyak sesi dengan geseran atau ralat JS. Metrik dan arah sama kekal senyap selama seminggu (boleh dilaraskan). Peristiwa ini tidak tergolong pada sebarang sesi: session_id dan session_url ialah null, link_url membuka gambaran keseluruhan projek, dan subject_id menamakan metrik, arah dan hari. Membawa metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score dan summary yang boleh dibaca serta hint. Tiada data pelawat. Untuk Web Vitals, measurements menggantikan sessions, dan page (kosong untuk seluruh laman) serta device (desktop atau mobil) menyatakan tempat ia berlaku; link_url kemudian membuka tab Web Vitals. |
rage_click | Apabila klik akibat geram dikesan |
error_detected | Apabila pengecualian bahagian hadapan berlaku |
ce | Langganan kolektif untuk peristiwa tersuai anda sendiri. Ia tidak merangkumi peristiwa di atas — semuanya mempunyai suis sendiri. |
7. Ralat & kod status
| Status | Maksud |
|---|---|
200 | Berjaya. |
401 | Kunci API tiada, salah bentuk atau dibatalkan. |
404 | Projek atau sesi diminta tidak wujud atau tidak tergolong dalam ruang kerja anda. |
429 | Had kadar dilebihi — anda menghantar lebih daripada 60 permintaan/minit dengan kunci ini. |
403 | Pelan ruang kerja tidak merangkumi REST API. Mesej menyatakan pelan diperlukan dan pelan semasa. |
8. Nota keselamatan
- Kunci baca sahaja (mp_ro_) tidak boleh mengubah apa-apa. Kunci tulis (mp_rw_) hanya boleh melampirkan ID pelanggan; tiada kunci boleh memadam data atau mengeksport data main semula mentah.
- Setiap permintaan diskopkan secara automatik kepada ruang kerja pemilik kunci — tiada cara menghantar ID ruang kerja lain untuk melihat data orang lain.
- Batalkan kunci pada bila-bila masa daripada /api-keys; pembatalan berkuat kuasa serta-merta.
- Anggap kunci API seperti kata laluan. Jika anda tersilap memasukkannya ke repositori awam melalui commit, batalkan serta-merta dan cipta yang baharu.
Halaman peristiwa terhad (API v1, 14 Oktober 2026)
GET /api/v1/sessions/{session_id}/events mengembalikan sehingga 100 peristiwa secara lalai. Tetapkan per_page kepada integer dari 1 hingga 100. Ikuti pagination.next_cursor dengan menghantar cursor tanpa perubahan pada permintaan seterusnya; kekalkan sesi dan ruang kerja yang sama. Peristiwa disusun mengikut created_at dan event_id. Kursor ditandatangani dan diikat pada sesi serta ruang kerja itu. Tiada jumlah keseluruhan atau halaman angka dikembalikan.
Tatasusunan data dan peta params sedia ada kekal tersedia. pagination.returned ialah bilangan sebenar dikembalikan; pagination.has_more menunjukkan halaman lain. next_cursor ialah null apabila lengkap. Respons dihadkan kepada 524288 bait, jadi halaman mungkin mengandungi peristiwa lebih sedikit daripada per_page. Setiap peristiwa mengembalikan maksimum 128 baris parameter; params_truncated ialah true jika ada lebih banyak. Parameter rentetan individu mengekalkan had pangkalan data 255 aksara. Parameter dipotong tidak tersedia melalui titik akhir ini. Mengurangkan per_page tidak meningkatkan had parameter.
Saiz halaman tidak sah, kursor diubah dan kursor bagi sesi/ruang kerja lain mengembalikan 400. Data peristiwa individu terlalu besar mengembalikan 413. Semakan akses sedia ada masih mengembalikan 401, 403, 404 atau 409 mengikut keadaan.
Had kekal 60 permintaan disahkan bagi setiap kunci API seminit. Kehabisan kuota mengembalikan 429 dengan Retry-After: 60. Jika Redis atau pengehad tidak tersedia, permintaan mengembalikan 503 dengan Retry-After: 5; ia tidak pernah diterima tanpa had. Patuhi Retry-After dan tambah sela menunggu rawak; jangan cuba semula dalam gelung rapat. Kegagalan pangkalan data peristiwa turut mengembalikan 503. Kursor tidak membekukan petikan: sisipan serentak dengan cap masa lebih lama mungkin memerlukan imbasan baharu.
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 ialah laluan kawalan bahagian belakang khusus Dev untuk pratonton SDK natif. Ia kekal dinyahaktifkan dalam produksi. Kunci Bearer bahagian belakang memerlukan skop baca untuk list/replay dan skop tulis untuk register/grant/delete/disable. Semakan tambahan ketersediaan pratonton natif terpakai. Jangan sekali-kali membenamkan kunci API ruang kerja kekal dalam aplikasi mudah alih.