API Reference

Complete reference for the Rehearsals JavaScript API and REST API.

JavaScript API

Global Objects

window.deepPredictionSettings

Configuration object that must be defined before loading the recorder script.

interface RehearsalsSettings {
  apiKey: string;           // Required: Your API key
  organizationId: string;   // Required: Your organization ID
  cookieDomain?: string;    // Optional: Cookie domain for cross-subdomain tracking
  disabled?: boolean;       // Optional: Disable recording
  sampleRate?: number;      // Optional: Sample rate (0.0 - 1.0)
  [key: string]: any;       // Additional custom settings
}

window.rehearsals

Main Rehearsals object available after initialization.

interface RehearsalsAPI {
  version: string;
  sessionId: string;
  isRecording(): boolean;
  startRecording(): void;
  stopRecording(): void;
  pauseRecording(): void;
  resumeRecording(): void;
  trackEvent(name: string, properties?: object): void;
  trackPageView(options?: PageViewOptions): void;
  identify(userId: string, traits?: object): void;
  updateConfig(settings: Partial<RehearsalsSettings>): void;
  destroy(): void;
}

Core Methods

startRecording()

Manually start recording (if not auto-started).

window.rehearsals.startRecording();

stopRecording()

Stop recording for the current session.

window.rehearsals.stopRecording();

pauseRecording() / resumeRecording()

Temporarily pause and resume recording.

// Pause during sensitive operation
window.rehearsals.pauseRecording();

// Resume after operation
window.rehearsals.resumeRecording();

Event Tracking

trackEvent(name, properties)

Track custom events within recordings.

// Simple event
window.rehearsals.trackEvent('button_clicked');

// Event with properties
window.rehearsals.trackEvent('purchase_completed', {
  value: 99.99,
  currency: 'USD',
  itemCount: 3,
  category: 'electronics'
});

// Form submission
window.rehearsals.trackEvent('form_submitted', {
  formId: 'contact-form',
  fields: ['name', 'email', 'message']
});

trackPageView(options)

Manually track page views (useful for SPAs).

// Simple page view
window.rehearsals.trackPageView();

// With options
window.rehearsals.trackPageView({
  url: '/products/widget',
  title: 'Widget Product Page',
  referrer: document.referrer
});

User Identification

identify(userId, traits)

Associate sessions with user IDs and traits.

// Simple identification
window.rehearsals.identify('user_123');

// With user traits
window.rehearsals.identify('user_123', {
  email: 'user@example.com',
  name: 'John Doe',
  plan: 'premium',
  createdAt: '2024-01-15',
  customAttributes: {
    industry: 'SaaS',
    company: 'Acme Corp'
  }
});

Session Data

Accessing Session Information

// Get current session ID
const sessionId = window.rehearsals.sessionId;

// Also available as
const sessionId = window.rhSessionId;

// Check if recording
const isRecording = window.rehearsals.isRecording();

Session Metadata

// Add metadata to current session
window.rehearsals.setSessionData({
  experiment: 'checkout-flow-v2',
  variant: 'control',
  source: 'email-campaign'
});

Configuration Updates

updateConfig(settings)

Update configuration dynamically.

// Disable recording temporarily
window.rehearsals.updateConfig({ disabled: true });

// Change sample rate
window.rehearsals.updateConfig({ sampleRate: 0.1 });

// Update multiple settings
window.rehearsals.updateConfig({
  disabled: false,
  sampleRate: 1.0,
  enableConsoleLog: true
});

Utility Methods

destroy()

Clean up and remove Rehearsals.

// Completely remove Rehearsals
window.rehearsals.destroy();

Debug Methods

// Enable debug logging
window.rhEnableDebug();

// Disable debug logging
window.rhDisableDebug();

// Get debug state
window.rhIsDebugEnabled();

REST API

Base URL: https://api.runrehearsals.com/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer dp_proj_xxxxx

Endpoints

GET /sessions

Retrieve sessions for your project.

curl -X GET "https://api.runrehearsals.com/v1/sessions" \
  -H "Authorization: Bearer dp_proj_xxxxx" \
  -H "Content-Type: application/json"

Query Parameters:

• limit (number): Max results per page (default: 50)
• offset (number): Pagination offset
• userId (string): Filter by user ID
• startDate (ISO 8601): Start date range
• endDate (ISO 8601): End date range

Response:

{
  "sessions": [
    {
      "id": "sess_abc123",
      "userId": "user_123",
      "startTime": "2024-01-15T10:30:00Z",
      "duration": 125000,
      "pageViews": 5,
      "events": 12,
      "metadata": {}
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

GET /sessions/{sessionId}

Get details for a specific session.

curl -X GET "https://api.runrehearsals.com/v1/sessions/sess_abc123" \
  -H "Authorization: Bearer dp_proj_xxxxx"

POST /events

Send custom events programmatically.

curl -X POST "https://api.runrehearsals.com/v1/events" \
  -H "Authorization: Bearer dp_proj_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_abc123",
    "name": "api_called",
    "properties": {
      "endpoint": "/users",
      "method": "POST",
      "status": 200
    }
  }'

DELETE /sessions/{sessionId}

Delete a specific session (GDPR compliance).

curl -X DELETE "https://api.runrehearsals.com/v1/sessions/sess_abc123" \
  -H "Authorization: Bearer dp_proj_xxxxx"

POST /users/{userId}/delete

Delete all data for a user (GDPR compliance).

curl -X POST "https://api.runrehearsals.com/v1/users/user_123/delete" \
  -H "Authorization: Bearer dp_proj_xxxxx"

Webhooks

Configure webhooks to receive real-time events.

Webhook Events

• session.started - New session began
• session.ended - Session completed
• event.tracked - Custom event recorded
• user.identified - User identification

Webhook Payload

{
  "event": "session.started",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "sessionId": "sess_abc123",
    "userId": "user_123",
    "url": "https://example.com/products",
    "userAgent": "Mozilla/5.0...",
    "metadata": {}
  }
}

Webhook Security

Verify webhook signatures:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return hash === signature;
}

Rate Limits

• API Calls: 1000 requests per minute
• Sessions: Based on your plan
• Events: 100 events per session

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642255200

Error Codes