Skip to content

Browser SDK

Lightweight client-side tracking SDK for sending user events, identifying users, and tracking page views. Published as @pyrx/synapse-browser on npm. Approximately 5 KB minified.

Installation

Drop the snippet into your HTML <head> to start tracking immediately.

html
<script>
!function(){var s=window.synapse=window.synapse||function(){
(s.q=s.q||[]).push(arguments)};
var e=document.createElement("script");
e.type="text/javascript";e.async=true;
e.src="https://storage.googleapis.com/cep-mvp-sdk/sdk/v1/synapse.min.js";
var x=document.getElementsByTagName("script")[0];
x.parentNode.insertBefore(e,x);
}();
 
synapse('init', { apiKey: 'psk_live_YOUR_API_KEY' });
synapse('page');
</script>

Commands called before the SDK script loads are queued and replayed automatically.

npm (For Bundlers)

bash
npm install @pyrx/synapse-browser
typescript
import { synapse } from '@pyrx/synapse-browser';
 
synapse('init', { apiKey: 'psk_live_YOUR_API_KEY' });
Warning

The Browser SDK sends the API key in request headers. Always use a browser-scoped API key for client-side code. Browser keys can only track events -- they cannot send emails, read contacts, or access admin endpoints. Create one in Dashboard > Settings > API Keys under the "Client-side" section.

Never use a data, full, or management scoped key in client-side code.

Initialization

javascript
synapse('init', {
apiKey: 'psk_live_YOUR_API_KEY', // Required
endpoint: 'https://synapse-events.pyrx.tech', // Default
flushInterval: 5000, // ms between flushes (default: 5000)
flushSize: 10, // events before auto-flush (default: 10)
debug: false, // Console logging (default: false)
});
ParameterTypeDefaultDescription
apiKeystringrequiredYour Synapse API key (browser scope recommended for client-side)
endpointstringhttps://synapse-events.pyrx.techEvent ingestion endpoint
flushIntervalnumber5000Milliseconds between automatic queue flushes
flushSizenumber10Number of queued events that trigger an immediate flush
debugbooleanfalseEnable [Synapse] console logging

Identify Users

Call after login to associate events with a known user.

javascript
synapse('identify', 'user-123', {
email: '[email protected]',
first_name: 'Jane',
last_name: 'Doe',
phone: '+1234567890',
});

The identify call:

  • Persists the user ID in localStorage so subsequent track calls include it automatically
  • Sends a $identify event with the provided traits
  • Sets contact_overrides with email, first_name, last_name, and phone fields (when provided) to upsert the contact server-side

Track Events

javascript
synapse('track', 'cart.abandoned', {
product: 'Widget',
price: 29.99,
currency: 'USD',
});
 
synapse('track', 'feature.used', {
feature: 'export_csv',
rows: 1500,
});

Events are queued in memory and flushed in batches to POST /v1/events/batch.

Page Views

javascript
// Automatically captures URL, path, title, and referrer
synapse('page');
 
// With custom properties
synapse('page', { section: 'pricing' });

Page views are tracked as $pageview events with automatic capture of url, path, title, and referrer.

Reset (On Logout)

javascript
synapse('reset');

Clears the identified user, generates a new anonymous ID, and removes the stored user ID from localStorage. Call this when a user logs out to prevent events from being attributed to the wrong user.

How It Works

  1. Events are queued in memory and persisted to localStorage
  2. The queue flushes every 5 seconds or when 10 events accumulate (configurable)
  3. Events are sent as a batch to POST /v1/events/batch
  4. On page unload, sendBeacon ensures queued events are delivered
  5. Failed flushes retry with exponential backoff (1s, 2s, 4s, up to 3 retries)
  6. The queue survives page refreshes via localStorage (max 500 events)

Anonymous Tracking

Before identify is called, events are associated with an auto-generated anonymous ID stored in localStorage. After identify, the user ID replaces the anonymous ID. The anonymous ID is always included as _anonymous_id in event attributes for server-side identity stitching.

Data Flow

Browser SDK
-> queue in memory + localStorage
-> batch POST /v1/events/batch (every 5s or 10 events)
-> Synapse API -> event processing pipeline
-> triggers flows, updates contacts, BigQuery streaming

Full Example

A complete integration for a SaaS application.

html
<!DOCTYPE html>
<html>
<head>
<script>
!function(){var s=window.synapse=window.synapse||function(){
(s.q=s.q||[]).push(arguments)};
var e=document.createElement("script");
e.type="text/javascript";e.async=true;
e.src="https://storage.googleapis.com/cep-mvp-sdk/sdk/v1/synapse.min.js";
var x=document.getElementsByTagName("script")[0];
x.parentNode.insertBefore(e,x);
}();
 
synapse('init', { apiKey: 'psk_live_YOUR_API_KEY' });
synapse('page');
</script>
</head>
<body>
<script>
// After user logs in
function onLogin(user) {
synapse('identify', user.id, {
email: user.email,
first_name: user.firstName,
last_name: user.lastName,
});
synapse('track', 'user.logged_in', {
method: 'email',
});
}
 
// Track feature usage
function onFeatureUsed(featureName) {
synapse('track', 'feature.used', {
feature: featureName,
timestamp: new Date().toISOString(),
});
}
 
// On logout
function onLogout() {
synapse('track', 'user.logged_out');
synapse('reset');
}
</script>
</body>
</html>

React / Next.js Integration

Tracking Hook

tsx
// hooks/useSynapse.ts
import { useEffect } from 'react';
 
export function useSynapseIdentify(user: { id: string; email: string; name: string } | null) {
useEffect(() => {
if (!user || typeof window === 'undefined') return;
const synapseFn = (window as any).synapse;
if (synapseFn) {
synapseFn('identify', user.id, {
email: user.email,
first_name: user.name.split(' ')[0],
});
}
}, [user]);
}
 
export function trackEvent(name: string, props?: Record<string, unknown>) {
if (typeof window !== 'undefined') {
const synapseFn = (window as any).synapse;
if (synapseFn) synapseFn('track', name, props);
}
}

Next.js Script Loading

tsx
// app/layout.tsx
import Script from 'next/script';
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<head>
<Script id="synapse-loader" strategy="afterInteractive" src="/scripts/synapse-init.js" />
</head>
<body>{children}</body>
</html>
);
}

Create /public/scripts/synapse-init.js with your init snippet:

javascript
// public/scripts/synapse-init.js
!function(){var s=window.synapse=window.synapse||function(){
(s.q=s.q||[]).push(arguments)};
var e=document.createElement("script");
e.type="text/javascript";e.async=true;
e.src="https://storage.googleapis.com/cep-mvp-sdk/sdk/v1/synapse.min.js";
var x=document.getElementsByTagName("script")[0];
x.parentNode.insertBefore(e,x);
}();
 
synapse('init', { apiKey: 'YOUR_API_KEY' });
synapse('page');

TypeScript Types

The SDK exports TypeScript types for configuration and events.

typescript
import type { SynapseConfig, SynapseEvent } from '@pyrx/synapse-browser';
 
interface SynapseConfig {
apiKey: string;
endpoint?: string;
flushInterval?: number;
flushSize?: number;
debug?: boolean;
}
 
interface SynapseEvent {
event_name: string;
user_id?: string;
attributes: Record<string, unknown>;
occurred_at: string;
idempotency_key: string;
source: "sdk";
contact_overrides?: Record<string, string>;
}

Limits and Constraints

ConstraintValue
Max queue size500 events
Max batch size per flush50 events
Max retries on failure3
Default flush interval5 seconds
Default flush threshold10 events

Method Reference

CommandArgumentsDescription
synapse('init', config)SynapseConfigInitialize the SDK with your API key
synapse('identify', userId, traits)string, object?Associate events with a known user
synapse('track', eventName, props)string, object?Track a custom event
synapse('page', props)object?Track a page view with automatic URL capture
synapse('reset')noneClear user identity and generate new anonymous ID