API Publik & Kunci API

1. Ringkasan

API MousePlayer memungkinkan Anda mengambil data dari ruang kerja ke dasbor sendiri, gudang data, atau alat internal. Selain melampirkan ID pelanggan ke sesi (identify, memerlukan kunci dengan cakupan tulis, lihat Cakupan kunci), API bersifat hanya baca: tidak ada data yang dapat diubah atau dihapus melalui API.

• URL Dasar: https://www.mouseplayer.com/api/v1/
• Semua respons berupa JSON.
• Setiap permintaan diautentikasi dengan kunci API dan otomatis dibatasi pada ruang kerja pemilik kunci — kunci dari satu ruang kerja tidak pernah dapat melihat data ruang kerja lain, bahkan secara tidak sengaja.
• Rekaman pemutaran ulang sesi lengkap (gerakan mouse, snapshot DOM) tidak tersedia melalui API. Anda mendapatkan metadata sesi, tampilan halaman, peristiwa kustom, dan segmen — cukup untuk membuat laporan dan dasbor tanpa memindahkan payload pemutaran ulang mentah.

2. Autentikasi

Buat dan kelola kunci API Anda pada Kunci API di menu akun (/api-keys). Hanya pemilik dan admin ruang kerja yang dapat membuat atau mencabut kunci.

Kirim kunci sebagai token Bearer dalam header Authorization pada setiap permintaan:

Kunci yang tidak ada, salah format, atau dicabut menerima respons 401:

Persyaratan Paket

REST API merupakan bagian dari paket Business dan Enterprise. Paket diambil dari pemilik ruang kerja, sehingga anggota tim yang diundang mewarisinya. Pemeriksaan dijalankan pada setiap permintaan, bukan hanya saat kunci dibuat — jika paket ruang kerja diturunkan, kunci yang ada berhenti berfungsi dan mengembalikan 403.

Cakupan Kunci

Setiap kunci membawa cakupannya dalam prefiksnya sendiri, sehingga Anda dapat mengetahui fungsi kunci hanya dengan melihatnya — dalam .env, tiket, atau terminal.

3. Batas Permintaan

Setiap kunci API dibatasi hingga 60 permintaan per menit, dihitung dalam rentang waktu bergulir. Setelah terlampaui, permintaan menerima respons 429 hingga rentang waktu berlalu:

4. Endpoint

GET/api/v1/projects

Mencantumkan setiap proyek (situs yang dilacak) dalam ruang kerja Anda.

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

Mencantumkan sesi pengunjung yang direkam untuk proyek, dari yang terbaru. Menggunakan paginasi.

GET/api/v1/sessions/{session_id}

Metadata satu sesi beserta tampilan halamannya. Sengaja tidak menyertakan payload pemutaran ulang lengkap — gunakan Pemutar pada dasbor untuk itu.

GET/api/v1/sessions/{session_id}/events

Peristiwa kustom yang dipicu selama sesi (peristiwa sama yang Anda kirim dengan mp('event', ...)), termasuk parameternya.

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

Mencantumkan segmen pengunjung yang ditentukan untuk proyek (segmen khusus proyek maupun seluruh ruang kerja).

5. Melampirkan ID Pelanggan dari Backend Anda

Browser sering tidak mengetahui siapa penggunanya. Dalam produk B2B, identitas diketahui setelah masuk — di backend Anda. Dalam toko, diketahui saat konfirmasi pesanan. Endpoint ini untuk saat tersebut.

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 daftar sesi, dapat dicari di sana, dan webhook session_identified dipicu — begitulah ID mencapai CRM Anda.

6. Webhook: Memverifikasi Tanda Tangan

Webhook dikonfigurasi per proyek pada Integrasi, tempat Anda juga menemukan rahasia penandatanganan. Setiap pengiriman membawa header berikut:

Tanda tangan adalah HMAC-SHA256 atas timestamp + "." + raw body, menggunakan rahasia penandatanganan proyek 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');

Pengiriman dan Percobaan Ulang

Pengiriman gagal dicoba ulang setelah 1 menit, 5 menit, 15 menit, 1 jam, dan 6 jam, lalu dihentikan. Respons 4xx selain 408 dan 429 tidak dicoba ulang — berarti "bukan dengan cara ini", bukan "bukan sekarang". Balas 2xx dengan cepat dan kerjakan sesudahnya; pengiriman mencapai batas waktu setelah 10 detik.

Peristiwa yang Tersedia

7. Kesalahan & Kode Status

8. Catatan Keamanan

• Kunci hanya baca (mp_ro_) tidak dapat mengubah apa pun. Kunci tulis (mp_rw_) hanya dapat melampirkan ID pelanggan; tidak ada kunci yang dapat menghapus data atau mengekspor data pemutaran ulang mentah.
• Setiap permintaan otomatis dibatasi pada ruang kerja kunci itu sendiri — tidak ada cara mengirim ID ruang kerja lain dan melihat data orang lain.
• Cabut kunci kapan saja dari /api-keys; pencabutan langsung berlaku.
• Perlakukan kunci API seperti kata sandi. Jika tidak sengaja memasukkannya ke repositori publik, segera cabut dan buat kunci baru.