Skip to content

JavaScript SDK

Lightweight client-side tracking SDK for sending user events, identifying users, and tracking page views to the Synapse event ingestion API. Approximately 5.3 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
pnpm add @pyrx/synapse-browser
typescript
import { synapse } from '@pyrx/synapse-browser';
 
synapse('init', { apiKey: 'psk_live_YOUR_API_KEY' });
Note

The SDK is designed for browser environments. It uses localStorage for queue persistence and sendBeacon for reliable delivery on page unload.

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
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
  • 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.

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.

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
Warning

The SDK sends the API key in request headers and query parameters (for sendBeacon). Use a data-scoped key to limit the blast radius. Never use a full or management scoped key in client-side code.

Server-Side Event Ingestion

For server-side event ingestion (Node.js, Python, etc.), use the REST API directly rather than this client-side SDK. See the API Reference and Python SDK for server-side integration patterns.