SDK Documentation

Integrate FPSentinel
in under 2 minutes

A lightweight JavaScript SDK that tracks FPS, detects frame drops, observes long tasks, and captures Web Vitals with zero configuration.

Getting Started

Installation

Install the FPSentinel SDK as a development dependency using your preferred package manager:

npm

npm install fpsentinel

Quick Start

Initialize FPSentinel with your API key. The SDK will automatically start tracking FPS, detecting frame drops, and capturing Web Vitals.

app.ts

import { initFPSentinel } from 'fpsentinel';

// Initialize with your API key from the dashboard
const destroy = initFPSentinel({
  apiKey: 'fps_live_a1b2c3d4e5f6g7h8i9j0',
});

// Optional: call destroy() when your app unmounts
// destroy();

💡 Tip: You can find your API key in the Projects page of your dashboard.

Configuration

Configuration Options

Customize the SDK behavior with these configuration options:

config.ts

initFPSentinel({
  apiKey: 'your-api-key',       // Required: Your project API key
  endpoint: '/api/ingest',       // Custom ingest endpoint
  batchSize: 50,                 // Events per batch (default: 50)
  batchInterval: 5000,           // Batch send interval in ms (default: 5000)
  trackFps: true,                // Enable FPS tracking (default: true)
  trackFrameDrops: true,         // Enable frame drop detection (default: true)
  trackWebVitals: true,          // Enable Web Vitals capture (default: true)
  trackLongTasks: true,          // Enable long task observation (default: true)
  frameDropThreshold: 50,        // Frame drop threshold in ms (default: 50)
  fpsReportInterval: 5000,       // FPS reporting interval in ms (default: 5000)
  fpsChangeThreshold: 2,         // Threshold for reporting FPS change (default: 2)
  debug: false,                  // Enable debug logging (default: false)
});

Option	Type	Default	Description
`apiKey`	`string`	—	Your project API key (required)
`endpoint`	`string`	`/api/ingest`	Custom ingest endpoint URL
`batchSize`	`number`	`50`	Number of events per batch
`batchInterval`	`number`	`5000`	Batch send interval (ms)
`trackFps`	`boolean`	`true`	Enable FPS tracking
`trackFrameDrops`	`boolean`	`true`	Enable frame drop & jank detection
`trackWebVitals`	`boolean`	`true`	Enable Web Vitals tracking
`trackLongTasks`	`boolean`	`true`	Enable Long Task observation
`frameDropThreshold`	`number`	`50`	Threshold for frame drop detection (ms)
`fpsReportInterval`	`number`	`5000`	How often to sample FPS (ms)
`debug`	`boolean`	`false`	Enable console logging for debugging

Features

FPS Tracking

The SDK uses requestAnimationFrame to measure the actual frame rate of your application. To minimize network noise, the SDK only reports FPS if it has changed by more than 2 frames since the last report.

Performance

Frame Drops & Jank

The SDK monitors the time delta between frames.

Frame Drop: Recorded when a single frame takes longer than the threshold (default: 50ms).
Jank: Recorded when a frame takes significantly longer (2x threshold), indicating visible stutter.

Web Vitals

The SDK automatically captures Core Web Vitals and additional performance metrics:

LCP (Largest Contentful Paint)
CLS (Cumulative Layout Shift)
INP (Interaction to Next Paint)
FCP (First Contentful Paint)
TTFB (Time to First Byte)

Analysis

Long Tasks

Using the PerformanceObserver API, the SDK detects "Long Tasks" that block the main thread for more than 50ms. These are captured with their duration and attribution data.

Event Batching & Transport

To ensure zero impact on your application's performance:

Batching: Events are queued and sent in bulk (default: every 50 events or 5 seconds).
Beacon API: Uses navigator.sendBeacon for reliable delivery even when the user closes the page.
Lifecycle Aware: Automatically flushes all queued events when the page is hidden or unloaded.

Integrate FPSentinelin under 2 minutes