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

Script Tag (Recommended)

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

html

!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)

});

Parameter	Type	Default	Description
`apiKey`	string	required	Your Synapse API key
`endpoint`	string	`https://synapse-events.pyrx.tech`	Event ingestion endpoint
`flushInterval`	number	5000	Milliseconds between automatic queue flushes
`flushSize`	number	10	Number of queued events that trigger an immediate flush
`debug`	boolean	false	Enable `[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

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

Partial-Accept Handling (SDK 0.5.0+)

From version 0.5.0, the SDK sends the X-Synapse-SDK-Version: 2 header and reads the batch endpoint's partial-accept response. It reconciles the local queue per rejected event:

invalid_schema events are dropped permanently. A malformed event can never be accepted, so re-queuing it would stall the queue forever. The SDK logs a console.warn naming the event's index and detail so you can fix your instrumentation.
over_limit events (and any unrecognized future reason) are re-queued and retried later with the existing exponential backoff — a workspace at its quota backs off rather than dropping data.
Accepted events are cleared from the queue as before.

A 422 response (every event was invalid_schema) drops those events instead of re-queuing the whole batch. Any other non-2xx status (403 over-quota, 429, 5xx) re-queues the whole batch for a later attempt.

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

Constraint	Value
Max queue size	500 events
Max batch size per flush	50 events
Max retries on failure	3
Default flush interval	5 seconds
Default flush threshold	10 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.