Node — Configuration
Configure the Node client withcreateSignalNode(options). Required: apiKey. Optional: endpoint (defaults to https://api.trysignal.ai/).
createSignalNode options
Available methods
After creating a client withcreateSignalNode(), 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. PasssessionId and windowId from request headers to correlate with client sessions.
When to use: Track any business event (e.g.
order_created, payment_processed, user_action). Events are queued and sent in batches.
identify(options)
Identify a user and set their properties. Sends an$identify event.
When to use: After login or when you know the user’s identity. Subsequent events will be associated with this user.
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).
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).
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).
groupIdentify(options, sessionId?, windowId?)
Set or update group properties. Sends$groupidentify event.
When to use: Update group-level attributes (e.g. company plan, team size) without associating a user.
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.
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.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.
Client-side: tracing headers
For session correlation, the client must send tracing headers. Use @signal-js/browser (or React/Next.js/Vue) and setaddTracingHeaders: true (or an array of hostnames). See Vue or React for client options.
See also
- Initialization — Setup
- Flush and shutdown — flush(), shutdown()