API Umum & Kunci API

1. Ringkesan

API MousePlayer ngidinaken panjenengan njupuk data saking ruang kerja dhateng dasbor, data warehouse utawi piranti internal piyambak. Kajawi masang ID pelanggan ing sesi (identify, mbetahaken kunci kanthi cakupan nyerat, pirsani Cakupan kunci), API namung kanggé maos: boten wonten data ingkang saged dipunowahi utawi dipunbusak mawi API.

• URL Dhasar: https://www.mouseplayer.com/api/v1/
• Sedaya tanggapan awujud JSON.
• Saben panyuwunan dipunotentikasi mawi kunci API lan otomatis dipunwatesi ing ruang kerja pamilik kunci — kunci saking satunggal ruang kerja boten nate saged mirsani data ruang kerja sanès, sanajan tanpa sengaja.
• Rekaman sesi pepak (gerakan panuding, gambar DOM) boten dipunbabar mawi API. Panjenengan pikantuk metadata sesi, tampilan kaca, prastawa khusus lan segmen — cekap kanggé damel laporan lan dasbor tanpa ngirim payload rekaman mentah mrana-mriki.

2. Otentikasi

Damel lan atur kunci API ing Kunci API ing menu akun panjenengan (/api-keys). Namung pamilik ruang kerja lan admin ingkang saged damel utawi nyabut kunci.

Kintun kunci minangka token Bearer ing header Authorization saben panyuwunan:

Kunci ingkang boten wonten, wujudipun salah utawi dipuncabut nampi tanggapan 401 :

Kabetahan paket

REST API kalebet ing paket Business lan Enterprise . Paket dipunjupuk saking pamilik ruang kerja, saéngga anggota tim undhangan marisi. Pamriksan lumampah ing saben panyuwunan, sanès namung nalika damel kunci — menawi ruang kerja dipunturunaken, kunci ingkang sampun wonten mandheg lan mangsuli 403.

Cakupan kunci

Saben kunci nggawa cakupan ing ater-ateripun, mila panjenengan saged mangertos pakaryan kunci namung kanthi mirsani — ing .env, ing tiket, ing terminal.

3. Wates Laju

Saben kunci API dipunwatesi 60 panyuwunan saben menit, dipunétang ing rentang lumampah. Menawi nglangkungi, panyuwunan nampi tanggapan 429 ngantos rentang rampung:

4. Endpoint

GET/api/v1/projects

Dhaptar sedaya proyek (situs ingkang dipunlacak) ing ruang kerja panjenengan.

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

Dhaptar sesi pengunjung ingkang dipunrekam kanggé proyek, paling énggal rumiyin. Kanthi kaca.

GET/api/v1/sessions/{session_id}

Metadata satunggal sesi, kaliyan tampilan kacanipun. Sengaja boten nyakup payload rekaman pepak — ginakaken Pamuter dasbor kanggé punika.

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

Prastawa khusus ingkang dipunpicu ing sesi (prastawa ingkang sami kaliyan ingkang panjenengan kintun mawi mp('event', ...)), kalebet parameteripun.

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

Dhaptar segmen pengunjung ingkang dipuntemtokaken kanggé proyek (segmen khusus proyek lan sedaya ruang kerja).

5. Masang ID pelanggan saking backend panjenengan

Browser asring boten mangertos sinten ingkang lenggah. Ing produk B2B, identitas dipuntemtokaken sasampunipun mlebet — ing backend panjenengan. Ing toko, dipuntemtokaken nalika konfirmasi pesenan. Endpoint punika kanggé wekdal punika.

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 lajeng medal ing dhaptar sesi, saged dipunpadosi ing ngriku, lan webhook session_identified dipunpicu — kanthi mekaten tekan CRM panjenengan.

6. Webhook: mriksa tandha tangan

Webhook dipunatur saben proyek ing Integrasi, ing ngriku ugi wonten rahasia tandha tangan. Saben pangiriman nggawa header punika:

Tandha tangan punika HMAC-SHA256 tumrap timestamp + "." + raw body, kanthi rahasia tandha tangan proyek panjenengan minangka 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');

Pangiriman lan upaya malih

Pangiriman gagal dipuncobi malih sasampunipun 1 menit, 5 menit, 15 menit, 1 jam lan 6 jam, lajeng dipuntilar. 4xx Tanggapan 408 kajawi 429 lan boten dipuncobi malih — ateges "boten kanthi cara punika", sanès "boten sapunika". Wangsulana 2xx kanthi rikat lan tindakaken pakaryan sasampunipun; pangiriman entèk wekdal sasampunipun 10 detik.

Prastawa ingkang kasedhiya

7. Kesalahan & Kode Status

8. Cathetan Keamanan

• Kunci namung maos (mp_ro_) boten saged ngowahi punapa kemawon. Kunci nyerat (mp_rw_) namung saged masang ID pelanggan; boten wonten kunci ingkang saged mbusak data utawi ngekspor data rekaman mentah.
• Saben panyuwunan otomatis dipunwatesi ing ruang kerja pamilik kunci — boten saged ngintun ID ruang kerja béda kanggé mirsani data tiyang sanès.
• Cabut kunci kapan kemawon saking /api-keys; pencabutan langsung lumampah.
• Anggep kunci API kados sandhi. Menawi tanpa sengaja dipuncommit ing repositori umum, langsung cabut lan damel énggal.