Skip to main content

​
Node — Configuration

Configure the Node client with createSignalNode(options). Required: apiKey. Optional: endpoint (defaults to https://api.trysignal.ai/).

​
createSignalNode options

OptionTypeDefaultDescription
endpointstringhttps://api.trysignal.ai/API endpoint for sending events
apiKeystringrequiredAPI key for authentication
projectIdstring'default'Project ID
debugbooleanfalseEnable debug logging
flushBatchSizenumber20Flush when this many events are queued
flushIntervalnumber10000Flush interval in ms
timeoutnumber30000Request timeout in ms
compressionbooleantrueEnable gzip compression
personalApiKeystring''Personal API key (e.g. for feature flags)
fetchtypeof fetchglobalThis.fetchCustom fetch implementation

​
Available methods

After creating a client with createSignalNode(), you can call these methods on the instance. All methods are synchronous (return immediately) except flush() and shutdown() which are async.

​
capture(options)

Track custom events from the server. Pass sessionId and windowId from request headers to correlate with client sessions.
OptionTypeRequiredDescription
distinctIdstringyesUser identifier
eventstringyesEvent name
propertiesRecord<string, JsonType>noEvent properties
timestampDatenoWhen the event occurred (default: now)
groupsRecord<string, string>noGroups the user belongs to (e.g. { company: 'acme' })
sessionIdstringnoFrom x-signal-session-id header for client correlation
windowIdstringnoFrom x-signal-window-id header for client correlation
When to use: Track any business event (e.g. order_created, payment_processed, user_action). Events are queued and sent in batches. 
const { sessionId, windowId, distinctId } = getSessionInfo(req);

signal.capture({
  distinctId: distinctId || userId,
  event: 'order_created',
  properties: { orderId, amount },
  sessionId,
  windowId,
});
See Capture for details.

​
identify(options)

Identify a user and set their properties. Sends an $identify event.
OptionTypeRequiredDescription
distinctIdstringyesUser identifier
propertiesUserTraitsnoUser properties to set (e.g. email, name, plan)
sessionIdstringnoFrom header for client correlation
windowIdstringnoFrom header for client correlation
When to use: After login or when you know the user’s identity. Subsequent events will be associated with this user. 
signal.identify({
  distinctId: 'user_123',
  properties: { email: 'user@example.com', name: 'Jane' },
  sessionId,
  windowId,
});
See Identify for details.

​
setPersonProperties(distinctId, properties, sessionId?, windowId?)

Set or update user properties (overwrites existing). Sends $set event. When to use: Update user properties without sending an $identify event (e.g. when properties change after initial identification). 
signal.setPersonProperties('user_123', { plan: 'pro', role: 'admin' }, sessionId, windowId);

​
setPersonPropertiesOnce(distinctId, properties, sessionId?, windowId?)

Set user properties only if not already set. Sends $set_once event. When to use: One-time attributes that shouldn’t be overwritten (e.g. signupSource, firstPurchaseDate). 
signal.setPersonPropertiesOnce('user_123', { signupSource: 'organic' }, sessionId, windowId);
See Set person properties for details.

​
group(distinctId, groupType, groupKey, properties?, sessionId?, windowId?)

Associate a user with a group (e.g. company, organization). Sends $group_assign event. If properties are provided, also calls groupIdentify() to set group properties. When to use: When a user joins or is associated with a group (e.g. company, team, organization). 
signal.group('user_123', 'company', 'acme', { role: 'admin' }, sessionId, windowId);

​
groupIdentify(options, sessionId?, windowId?)

Set or update group properties. Sends $groupidentify event.
OptionTypeRequiredDescription
groupTypestringyese.g. 'company', 'organization'
groupKeystringyesGroup identifier
propertiesRecord<string, JsonType>noGroup properties to set
When to use: Update group-level attributes (e.g. company plan, team size) without associating a user. 
signal.groupIdentify(
  { groupType: 'company', groupKey: 'acme', properties: { plan: 'enterprise', seats: 50 } },
  sessionId,
  windowId
);
See Group for details.

​
alias(distinctId, alias, sessionId?, windowId?)

Link an alias (e.g. anonymous ID) to a user. Sends $create_alias event. When to use: After login to merge anonymous events (from before login) with the identified user. 
signal.alias('user_123', 'anonymous_abc', sessionId, windowId);
See Alias for details.

​
flush()

Flush all queued events to the server immediately. Returns a Promise. When to use: Before a response in serverless functions, after critical paths, or when you need to ensure events are sent immediately. 
await signal.flush();

​
shutdown()

Stop the flush timer and flush remaining events. Returns a Promise. Call before process exit for graceful shutdown. When to use: In cleanup handlers (e.g. process.on('SIGTERM', ...)) to ensure no events are lost when the process exits. 
await signal.shutdown();
See Flush and shutdown for details.

​
Client-side: tracing headers

For session correlation, the client must send tracing headers. Use @signal-js/browser (or React/Next.js/Vue) and set addTracingHeaders: true (or an array of hostnames). See Vue or React for client options.

​
See also