Herkese Açık API & API Anahtarları

1. Genel bakış

MousePlayer API, çalışma alanınızdaki verileri kendi gösterge panellerinize, veri ambarınıza veya dahili araçlarınıza almanızı sağlar. Oturumlara müşteri kimliği ekleme dışında (identify; yazma kapsamlı anahtar gerektirir, bkz. Anahtar kapsamları) salt okunurdur: API üzerinden veri değiştirilemez veya silinemez.

• Temel URL: https://www.mouseplayer.com/api/v1/
• Tüm yanıtlar JSON biçimindedir.
• Her istek bir API anahtarıyla doğrulanır ve otomatik olarak anahtarın ait olduğu çalışma alanıyla sınırlandırılır — bir çalışma alanının anahtarı, yanlışlıkla bile olsa başka bir çalışma alanının verilerini asla göremez.
• Tam oturum yeniden oynatma kaydı (fare hareketleri, DOM anlık görüntüleri) API üzerinden sunulmaz . Oturum üstverisini, sayfa görüntülemelerini, özel olayları ve segmentleri alırsınız — ham yeniden oynatma verisini taşımadan rapor ve gösterge panelleri oluşturmak için yeterlidir.

2. Kimlik doğrulama

API anahtarlarınızı hesap menünüzdeki API Anahtarları bölümünde (/api-keys) oluşturun ve yönetin. Yalnızca çalışma alanı sahipleri ve yöneticileri anahtar oluşturabilir veya iptal edebilir.

Anahtarı her istekte Bearer belirteci olarak şu başlıkta gönderin Authorization :

Eksik, hatalı biçimli veya iptal edilmiş anahtarlar şu yanıtı alır 401 :

Plan gereksinimi

REST API, Business ve Enterprise planlarına dahildir. Plan, çalışma alanının sahibinden alınır; böylece davet edilen ekip üyeleri de aynı plandan yararlanır. Kontrol yalnızca anahtar oluşturulurken değil, her istekte çalışır — çalışma alanının planı düşürülürse mevcut anahtarlar çalışmayı durdurur ve şu yanıtı döndürür: 403.

Anahtar kapsamları

Her anahtar, kapsamını kendi önekinde taşır. Böylece bir anahtarın ne yaptığını ona bakarak anlayabilirsiniz — bir .env içinde, bir destek kaydında veya terminalde.

3. İstek sınırları

Her API anahtarı kayan zaman aralığında izlenerek dakikada 60 istekle sınırlandırılır. Bu sınırı aştığınızda zaman aralığı temizlenene kadar istekler şu yanıtı alır 429 :

4. Uç noktalar

GET/api/v1/projects

Çalışma alanınızdaki her projeyi (takip edilen siteyi) listeler.

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

Bir proje için kaydedilen ziyaretçi oturumlarını en yeniden başlayarak listeler. Sayfalandırılır.

GET/api/v1/sessions/{session_id}

Tek bir oturumun üstverisi ve sayfa görüntülemeleri. Tam yeniden oynatma verisi özellikle dahil edilmez — bunun için gösterge panelindeki Oynatıcıyı kullanın.

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

Oturum sırasında tetiklenen özel olaylar (şu yöntemle gönderdiğiniz olaylarla aynıdır: mp('event', ...)) ve parametreleri.

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

Bir proje için tanımlanmış ziyaretçi segmentlerini listeler (hem projeye özgü hem çalışma alanı genelindeki segmentler).

5. Arka ucunuzdan müşteri kimliği ekleme

Tarayıcı çoğu zaman karşısında kimin olduğunu bilmez. B2B ürününde kimlik girişten sonra — arka ucunuzda belirlenir. Mağazada ise sipariş onayıyla belirlenir. Bu uç nokta tam olarak o an içindir.

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}}

Kimlik daha sonra oturum listesinde görünür, orada aranabilir ve şu webhook tetiklenir: session_identified — CRM'inize bu yolla ulaşır.

6. Webhook'lar: imzayı doğrulama

Webhook'lar proje başına şu bölümde yapılandırılır: Entegrasyonlar. İmzalama gizli anahtarını da burada bulursunuz. Her teslim şu başlıkları taşır:

İmza, şu veri üzerinde hesaplanan HMAC-SHA256 değeridir: timestamp + "." + raw body; anahtar olarak projenizin imzalama gizli anahtarı kullanılır.

// 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');

Teslim ve yeniden denemeler

Başarısız teslim şu aralıklarla yeniden denenir: 1 dk, 5 dk, 15 dk, 1 sa ve 6 sa; ardından vazgeçilir. 4xx türü yanıtlardan şu iki durum dışındakiler: 408 ve 429 , yeniden denenmez — bunlar "şimdi olmaz" değil, "bu şekilde olmaz" der. Hızlıca şu yanıtı verin: 2xx ; işi sonrasında yapın. Teslim 10 saniyede zaman aşımına uğrar.

Kullanılabilir olaylar

7. Hatalar & Durum Kodları

8. Güvenlik notları

• Salt okunur anahtarlar (mp_ro_) hiçbir şeyi değiştiremez. Yazma anahtarları (mp_rw_) yalnızca müşteri kimliği ekleyebilir; hiçbir anahtar veri silemez veya ham yeniden oynatma verilerini dışa aktaramaz.
• Her istek otomatik olarak anahtarın kendi çalışma alanıyla sınırlandırılır — farklı bir çalışma alanı kimliği gönderip başkasının verilerini görmenin yolu yoktur.
• Anahtarı istediğiniz zaman şu bölümden iptal edin: /api-keys; iptal anında geçerli olur.
• API anahtarınızı parola gibi koruyun. Yanlışlıkla herkese açık bir depoya eklerseniz hemen iptal edin ve yeni bir anahtar oluşturun.