SDK Reference

Complete API reference for the @summoniq/analytics package. Covers hooks, components, and the standalone client.

Last updated: 2026-04-12

useAnalytics()

The primary hook. Returns the core tracking functions.

import { useAnalytics } from '@summoniq/analytics/react';

const { track, pageView, identify, reset, client } = useAnalytics();

useTrackEvent()

Returns the track function directly. Useful when you only need to fire events and don't need identify/reset.

const track = useTrackEvent();
track('cta_clicked', { variant: 'hero' });

useTrackOnMount(eventName, properties?)

Fires an event once when the component mounts. Safe under React strict mode — won't double-fire.

import { useTrackOnMount } from '@summoniq/analytics/react';

function PricingPage() {
  useTrackOnMount('pricing_viewed', { source: 'nav' });
  return <div>...</div>;
}

useTrackOnUnmount(eventName, properties?)

Fires an event when the component unmounts.

import { useTrackOnUnmount } from '@summoniq/analytics/react';

function VideoPlayer() {
  useTrackOnUnmount('video_abandoned');
  return <video>...</video>;
}

<TrackClick>

Wraps a child element to track clicks without writing an onClick handler.

import { TrackClick } from '@summoniq/analytics/react';

<TrackClick eventName="download_clicked" properties={{ file: 'report.pdf' }}>
  <button>Download report</button>
</TrackClick>

The child's existing onClick handler is preserved.

<TrackVisibility>

Uses IntersectionObserver to fire an event when an element scrolls into view.

import { TrackVisibility } from '@summoniq/analytics/react';

<TrackVisibility
  eventName="testimonials_seen"
  threshold={0.5}
  triggerOnce={true}
>
  <section>...</section>
</TrackVisibility>

<WebVitals />

Drop this into your root layout alongside the provider to track Core Web Vitals (LCP, CLS, INP, TTFB, FCP). Each metric is sent as a web_vital event with a rating of "good", "needs-improvement", or "poor".

<AnalyticsProvider config={config}>
  <WebVitals />
  {children}
</AnalyticsProvider>

Tracking events

The track function accepts an event name and an optional properties object.

track('checkout_started', {
  cart_value: 49.99,
  item_count: 3,
  currency: 'USD',
});

Property values can be strings, numbers, booleans, or null.

Identifying users

Call identify after login to tie anonymous activity to a known user. Traits are optional but recommended.

identify(user.id, {
  email: user.email,
  name: user.name,
  plan: 'pro',
  company: 'Acme Inc',
});

Supported trait fields:

• email, name, firstName, lastName
• avatar, company, createdAt
• Any custom key-value pairs

Call reset() on logout to clear the stored identity and start a fresh anonymous session.

Auto-collected context

Every event automatically includes context the SDK collects from the browser:

• Page — URL, path, title, referrer, search params, hash
• Device — screen size, viewport, device type, language, timezone, OS, connection type
• Campaign — UTM parameters parsed from the URL automatically
• Session — session ID, start time, page view count, entry page, entry referrer

Event types

Each event has a type field set automatically:

Standalone client

If you're not using React, initialize the client directly:

import { initAnalytics, track, identify } from '@summoniq/analytics';

initAnalytics({
  appId: 'your-app-id',
  endpoint: 'https://api.signalsplash.com/api/events',
});

track('page_loaded');
identify('user_123', { email: 'user@example.com' });

The standalone client exposes the same track, pageView, identify, and reset functions as module-level exports.