Temps

React Analytics SDK

API reference for @temps-sdk/react-analytics. This package provides analytics, Web Vitals, session replay, and engagement tracking for React applications deployed on Temps.

Installation

npm install @temps-sdk/react-analytics

Requirements: React 18+ or React 19

TempsAnalyticsProvider

The root provider component. Wrap your application with it to enable analytics.

import { TempsAnalyticsProvider } from '@temps-sdk/react-analytics';

<TempsAnalyticsProvider basePath="/api/_temps">
  {children}
</TempsAnalyticsProvider>

Props

  • Name
    basePath
    Type
    string
    Description

    API endpoint path. When deployed on Temps, the proxy handles this automatically.

  • Name
    domain
    Type
    string
    Description

    Override the detected hostname. Use when not deployed on Temps or running locally.

  • Name
    disabled
    Type
    boolean
    Description

    Kill switch to disable all analytics.

  • Name
    ignoreLocalhost
    Type
    boolean
    Description

    Skip tracking on localhost, 127.0.0.1, and test environments.

  • Name
    autoTrackPageviews
    Type
    boolean
    Description

    Automatically track page views on pushState and popstate events.

  • Name
    autoTrackPageLeave
    Type
    boolean
    Description

    Track page_leave events with time-on-page via pagehide and beforeunload.

  • Name
    pageLeaveEventName
    Type
    string
    Description

    Custom event name for page leave tracking.

  • Name
    autoTrackSpeedAnalytics
    Type
    boolean
    Description

    Collect Core Web Vitals (LCP, FID, CLS, TTFB, FCP, INP).

  • Name
    autoTrackEngagement
    Type
    boolean
    Description

    Enable heartbeat-based engagement tracking.

  • Name
    heartbeatInterval
    Type
    number
    Description

    Engagement heartbeat interval in milliseconds.

  • Name
    inactivityTimeout
    Type
    number
    Description

    Milliseconds of no interaction before marking the user as inactive.

  • Name
    engagementThreshold
    Type
    number
    Description

    Milliseconds on page before the user is considered "engaged".

  • Name
    enableSessionRecording
    Type
    boolean
    Description

    Enable rrweb-based session recording.

  • Name
    sessionRecordingConfig
    Type
    SessionRecordingConfig
    Description

    Configuration object for session recording. See Session Recording Configuration.

useTempsAnalytics

The core analytics hook. Returns the full analytics context.

import { useTempsAnalytics } from '@temps-sdk/react-analytics';

const { trackEvent, trackPageview, identify, enabled } = useTempsAnalytics();

Return value

  • Name
    trackEvent
    Type
    (name: string, data?: Record<string, JsonValue>) => Promise<void>
    Description

    Send a custom event with optional properties.

  • Name
    trackPageview
    Type
    () => void
    Description

    Manually fire a pageview event.

  • Name
    identify
    Type
    (userId: string, traits?: Record<string, any>) => void
    Description

    Identify a user for analytics enrichment.

  • Name
    enabled
    Type
    boolean
    Description

    Whether analytics are currently active.

useTrackEvent

Convenience hook that returns only the trackEvent function.

import { useTrackEvent } from '@temps-sdk/react-analytics';

const track = useTrackEvent();
track('button_clicked', { id: 'cta-hero' });

useTrackPageview

Returns a function to manually trigger a pageview.

import { useTrackPageview } from '@temps-sdk/react-analytics';

const trackPageview = useTrackPageview();
useEffect(() => { trackPageview(); }, []);

usePageLeave

Track when users leave a page, including time spent.

import { usePageLeave } from '@temps-sdk/react-analytics';

const { triggerPageLeave } = usePageLeave({
  eventName: 'article_leave',
  eventData: { category: 'blog' },
  enabled: true,
});

Options

  • Name
    eventName
    Type
    string
    Description

    Event name for the page leave event.

  • Name
    eventData
    Type
    Record<string, JsonValue>
    Description

    Additional data merged into the event payload.

  • Name
    enabled
    Type
    boolean
    Description

    Enable or disable tracking.

Return value

  • Name
    triggerPageLeave
    Type
    () => void
    Description

    Manually trigger a page leave event (e.g. before client-side navigation).

The event payload automatically includes time_on_page_ms, url, referrer, and timestamp.

useSpeedAnalytics

Tracks Web Vitals performance metrics. Enabled by default through the provider.

import { useSpeedAnalytics } from '@temps-sdk/react-analytics';

useSpeedAnalytics({ basePath: '/api/_temps', disabled: false });

Metrics collected:

MetricFull nameWhat it measures
TTFBTime to First ByteServer responsiveness
FCPFirst Contentful PaintFirst pixels rendered
LCPLargest Contentful PaintMain content visible
FIDFirst Input DelayInput responsiveness
CLSCumulative Layout ShiftVisual stability
INPInteraction to Next PaintOverall responsiveness

Initial metrics (TTFB, FCP, LCP, FID) are batched into a single request. Late metrics (CLS, INP) are sent individually as they stabilize.

useEngagementTracking

Manual engagement tracking for specific pages or components.

import { useEngagementTracking } from '@temps-sdk/react-analytics';

const { engagementData, isTracking } = useEngagementTracking({
  heartbeatInterval: 15000,
  engagementThreshold: 5000,
  onEngagementUpdate: (data) => console.log(data),
  onPageLeave: (data) => console.log(data),
});

Engagement data shape

interface EngagementData {
  engagement_time_seconds: number;
  total_time_seconds: number;
  heartbeat_count: number;
  is_engaged: boolean;
  is_visible: boolean;
  time_since_last_activity: number;
}

useScrollVisibility

Track when elements scroll into view using Intersection Observer.

import { useScrollVisibility } from '@temps-sdk/react-analytics';

const ref = useScrollVisibility({
  eventName: 'pricing_viewed',
  eventData: { section: 'pricing' },
  threshold: 0.75,
  once: true,
});

return <section ref={ref}>Pricing Plans</section>;

Options

  • Name
    eventName
    Type
    string
    Description

    Event name to fire when the element is visible.

  • Name
    eventData
    Type
    Record<string, JsonValue>
    Description

    Additional event properties.

  • Name
    threshold
    Type
    number
    Description

    Visibility percentage (0.0 to 1.0) required to trigger.

  • Name
    once
    Type
    boolean
    Description

    Track only the first time the element becomes visible.

  • Name
    enabled
    Type
    boolean
    Description

    Enable or disable tracking.

  • Name
    root
    Type
    Element | null
    Description

    Scroll container (null = viewport).

  • Name
    rootMargin
    Type
    string
    Description

    Margin around the root element.

useSessionRecording

Control session recording programmatically.

import { useSessionRecording } from '@temps-sdk/react-analytics';

const {
  isRecordingEnabled,
  enableRecording,
  disableRecording,
  toggleRecording,
  sessionId,
} = useSessionRecording();

Return value

  • Name
    isRecordingEnabled
    Type
    boolean
    Description

    Whether recording is currently active.

  • Name
    enableRecording
    Type
    () => void
    Description

    Start recording.

  • Name
    disableRecording
    Type
    () => void
    Description

    Stop recording.

  • Name
    toggleRecording
    Type
    () => void
    Description

    Toggle recording on/off.

  • Name
    sessionId
    Type
    string | null
    Description

    The current session ID if recording.

Declarative tracking

Track click events without writing JavaScript using HTML attributes:

<button temps-event-name="cta_click" temps-data-section="hero" temps-data-variant="blue">
  Get Started
</button>

Any element with temps-event-name fires an event on click. All temps-data-* attributes are sent as event properties (with the temps-data- prefix stripped).

Session recording configuration

Pass to the provider as sessionRecordingConfig:

  • Name
    sessionSampleRate
    Type
    number
    Description

    Percentage of sessions to record (0.0 to 1.0). Use 0.1 for 10%.

  • Name
    maskAllInputs
    Type
    boolean
    Description

    Replace all input field values with asterisks. Password fields are always masked.

  • Name
    maskTextSelector
    Type
    string
    Description

    CSS selector for text elements to mask (e.g. [data-mask]).

  • Name
    blockClass
    Type
    string
    Description

    CSS class to completely hide elements from recordings.

  • Name
    ignoreClass
    Type
    string
    Description

    CSS class to exclude elements from capture.

  • Name
    maskTextClass
    Type
    string
    Description

    CSS class to mask text content.

  • Name
    excludedPaths
    Type
    string[]
    Description

    URL paths to exclude from recording. Supports wildcards (e.g. /admin/*).

  • Name
    recordCanvas
    Type
    boolean
    Description

    Record canvas element content.

  • Name
    collectFonts
    Type
    boolean
    Description

    Collect font data for accurate replay.

  • Name
    batchSize
    Type
    number
    Description

    Number of events per batch before sending.

  • Name
    flushInterval
    Type
    number
    Description

    Maximum time (ms) before flushing a batch.

Environment detection

When ignoreLocalhost is true (default), the SDK disables itself in:

EnvironmentDetection
Localhostlocalhost, 127.0.0.1, ::1, *.local
Test runnersjest, mocha, vitest, cypress globals detected
Manual overridelocalStorage.temps_ignore = "true"

TypeScript exports

All types are exported:

import type {
  AnalyticsContextValue,
  TempsAnalyticsProviderProps,
  EngagementData,
  EngagementTrackerOptions,
  WebVitalMetric,
  SpeedMetric,
  JsonValue,
} from '@temps-sdk/react-analytics';

Was this page helpful?