@summoniq/signalsplash-client-sdk
v1.1.3
Published
SignalSplash client SDK for analytics, sessions, and Web Vitals
Maintainers
bright-n-earlyReadme
@summoniq/signalsplash-client-sdk
A comprehensive analytics SDK for Next.js applications with multi-provider support, automatic session tracking, and Web Vitals integration.
Features
- Automatic page view tracking - Tracks page navigation in Next.js App Router
- Session management - Automatic session creation and timeout handling
- User identification - Identify users and track traits
- Web Vitals - Track LCP, FID, CLS, FCP, TTFB, and INP metrics
- Multi-provider support - SignalSplash (default), PostHog, or Vercel Analytics
- Event batching - Efficient event queue with automatic flushing
- UTM tracking - Automatic campaign parameter parsing
- Device detection - Mobile, tablet, desktop classification
- Privacy-friendly - Respects Do Not Track browser setting
Installation
In a monorepo (workspace)
If your app is in the same monorepo as this package:
# The package is automatically available via workspace resolution
bun add @summoniq/signalsplash-client-sdkStandalone project
For a standalone Next.js project, link the package:
# Option 1: Link the package globally
cd /path/to/signalsplash/packages/analytics
bun link
# Then in your project
cd /path/to/your-project
bun link @summoniq/signalsplash-client-sdk
# Option 2: Add as a local dependency (in package.json)
{
"dependencies": {
"@summoniq/signalsplash-client-sdk": "file:/path/to/signalsplash/packages/analytics"
}
}Peer Dependencies
Ensure you have the following peer dependencies installed:
bun add react next
bun add web-vitals # Optional, for Web Vitals trackingQuick Start
1. Add the Analytics Provider
Wrap your application with the AnalyticsProvider in your root layout:
// app/layout.tsx
import { AnalyticsProvider } from "@summoniq/signalsplash-client-sdk/react";
const analyticsConfig = {
appId: "your-app-id",
endpoint: "http://localhost:20000/api/events", // analytics-api URL
enabled: process.env.NODE_ENV === "production",
debug: process.env.NODE_ENV === "development",
};
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<AnalyticsProvider config={analyticsConfig}>
{children}
</AnalyticsProvider>
</body>
</html>
);
}2. Track Custom Events
Use hooks to track custom events in your components:
"use client";
import { useAnalytics, useTrackEvent } from "@summoniq/signalsplash-client-sdk/react";
function MyComponent() {
const { track, identify } = useAnalytics();
// Track a custom event
const handleButtonClick = () => {
track("button_clicked", {
button_name: "signup",
location: "hero_section",
});
};
// Identify a user after login
const handleLogin = (user: { id: string; email: string }) => {
identify(user.id, {
email: user.email,
name: user.name,
});
};
return <button onClick={handleButtonClick}>Sign Up</button>;
}3. Track Web Vitals (Optional)
Add the WebVitals component to track Core Web Vitals:
// app/layout.tsx
import { AnalyticsProvider, WebVitals } from "@summoniq/signalsplash-client-sdk/react";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<AnalyticsProvider config={analyticsConfig}>
<WebVitals />
{children}
</AnalyticsProvider>
</body>
</html>
);
}Configuration Options
interface AnalyticsConfig {
// Required: Unique identifier for your application
appId: string;
// Optional: API endpoint for sending events (default: '/api/analytics')
endpoint?: string;
// Optional: Enable/disable analytics (default: true)
enabled?: boolean;
// Optional: Enable debug logging (default: false)
debug?: boolean;
// Optional: Respect Do Not Track browser setting (default: true)
respectDoNotTrack?: boolean;
// Optional: Automatically track page views (default: true)
trackPageViews?: boolean;
// Optional: Track Web Vitals (default: true)
trackWebVitals?: boolean;
// Optional: Session timeout in minutes (default: 30)
sessionTimeout?: number;
// Optional: Provider configuration
provider?: ProviderConfig;
}Hooks Reference
useAnalytics()
Returns the full analytics context with all methods:
const { track, pageView, identify, reset, client } = useAnalytics();useTrackEvent()
Shorthand for tracking events:
const track = useTrackEvent();
track("event_name", { property: "value" });useTrackOnMount(eventName, properties?)
Track an event when a component mounts:
useTrackOnMount("page_viewed", { page: "dashboard" });useTrackOnUnmount(eventName, properties?)
Track an event when a component unmounts:
useTrackOnUnmount("modal_closed", { modal: "settings" });useWebVitals()
Start tracking Web Vitals (called automatically by <WebVitals /> component):
useWebVitals();Components Reference
<TrackClick>
Wrap any clickable element to track clicks:
import { TrackClick } from "@summoniq/signalsplash-client-sdk/react";
<TrackClick eventName="cta_clicked" properties={{ location: "header" }}>
<button>Get Started</button>
</TrackClick>;<TrackVisibility>
Track when an element becomes visible (using Intersection Observer):
import { TrackVisibility } from "@summoniq/signalsplash-client-sdk/react";
<TrackVisibility
eventName="section_viewed"
properties={{ section: "testimonials" }}
threshold={0.5}
triggerOnce={true}
>
<section>Testimonials content...</section>
</TrackVisibility>;Analytics API Integration
This SDK is designed to work with the analytics-api app, which receives and stores events.
analytics-api Endpoints
| Method | Endpoint | Description |
| ------ | --------------- | ------------------------ |
| POST | /api/events | Receive analytics events |
| GET | /api/events | Query stored events |
| GET | /api/sessions | Query sessions |
| GET | /api/summary | Get aggregated analytics |
| GET | /api/health | Health check |
Running the Analytics API
# From the summoniq monorepo root
bun dev:analytics-api
# Or directly
cd apps/analytics-api && bun devThe analytics-api runs on port 20000 by default.
Event Types
The SDK tracks the following event types:
| Type | Description |
| --------------- | -------------------------- |
| pageview | Page navigation events |
| track | Custom tracking events |
| identify | User identification events |
| session_start | Session started |
| session_end | Session ended |
| web_vital | Web Vitals metrics |
Event Structure
All events include the following context:
{
id: string; // Unique event ID
appId: string; // Your application ID
sessionId: string; // Current session ID
anonymousId: string; // Persistent anonymous ID
userId?: string; // Identified user ID (if set)
name: string; // Event name
type: EventType; // Event type
properties?: object; // Custom properties
timestamp: number; // Unix timestamp (ms)
context: {
page: { // Page information
url, path, title, referrer, search, hash, host
},
device: { // Device information
screenWidth, screenHeight, viewportWidth, viewportHeight,
devicePixelRatio, deviceType, language, timezone, touchEnabled
},
campaign?: { // UTM parameters (if present)
source, medium, campaign, term, content
},
userAgent: string,
sdkVersion: string
}
}Provider Configuration
SignalSplash (Default)
const config = {
appId: "my-app",
endpoint: "http://localhost:20000/api/events",
provider: {
provider: "applab",
endpoint: "http://localhost:20000/api/events", // Optional override
},
};PostHog
const config = {
appId: "my-app",
provider: {
provider: "posthog",
apiKey: "your-posthog-api-key",
apiHost: "https://app.posthog.com", // Optional, defaults to PostHog cloud
},
};Vercel Analytics
When using Vercel Analytics, the SDK will send events through Vercel's built-in analytics. Install @vercel/analytics separately:
const config = {
appId: "my-app",
provider: {
provider: "vercel",
},
};Environment Variables
Recommended environment variables for your app:
# Enable/disable analytics
NEXT_PUBLIC_ANALYTICS_ENABLED=true
# Analytics API endpoint (optional override)
# - In production, defaults to https://api.signalsplash.com/api/analytics
# - In development, defaults to /api/analytics unless overridden
NEXT_PUBLIC_ANALYTICS_ENDPOINT=
# Your app ID
NEXT_PUBLIC_ANALYTICS_APP_ID=my-app
# Debug mode (development only)
NEXT_PUBLIC_ANALYTICS_DEBUG=trueTypeScript Support
The package includes full TypeScript definitions. Import types as needed:
import type {
AnalyticsConfig,
AnalyticsEvent,
EventPropertyValue,
UserTraits,
Session,
} from "@summoniq/signalsplash-client-sdk";Module Exports
The package provides multiple entry points:
// Main exports (types)
import type { AnalyticsConfig, AnalyticsEvent } from "@summoniq/signalsplash-client-sdk";
// React integration (provider, hooks, components)
import { AnalyticsProvider, useAnalytics } from "@summoniq/signalsplash-client-sdk/react";
// Client-only (for non-React usage)
import { initAnalytics, track, identify } from "@summoniq/signalsplash-client-sdk/client";
// Server utilities
import { createStorage } from "@summoniq/signalsplash-client-sdk/server";
// Storage implementation
import { AnalyticsStorage } from "@summoniq/signalsplash-client-sdk/storage";Troubleshooting
Events not being sent
- Check that
enabledistruein your config - Verify the
endpointURL is correct and accessible - Enable
debug: trueto see console logs - Check browser DevTools Network tab for failed requests
Session not persisting
Sessions are stored in sessionStorage. If you're testing in incognito mode or clearing storage, sessions will reset.
Web Vitals not tracking
- Ensure
web-vitalspackage is installed - Add the
<WebVitals />component to your layout - Web Vitals are only reported once per page load
License
MIT