Skip to main content

Next.js — Set person properties

Update user properties without changing the distinct ID. Use setPersonProperties to overwrite properties or setPersonPropertiesOnce to set them only if not already set. Available on both client and server.

Client: useSignal

Get setPersonProperties and setPersonPropertiesOnce from useSignal():

Client: setPersonProperties(properties)

Sets or updates user properties (overwrites existing). Sends a $set event. When to use: Update user properties after initial identification (e.g. plan changes, role updates).

Client: setPersonPropertiesOnce(properties)

Sets user properties only if they are not already set. Sends a $set_once event. When to use: One-time attributes that shouldn’t be overwritten (e.g. signupSource, firstPurchaseDate).

Server: setPersonProperties(distinctId, properties, sessionId?, windowId?)

Sets or updates user properties from the server. Pass sessionId and windowId for client correlation.

Server: setPersonPropertiesOnce(distinctId, properties, sessionId?, windowId?)

Sets user properties only if not already set. Pass sessionId and windowId for client correlation.

Differences from identify()

  • identify(distinctId, traits) — Changes the user’s distinct ID and sets properties. Use after login.
  • setPersonProperties(properties) — Updates properties without changing the distinct ID. Use when properties change after identification.
  • setPersonPropertiesOnce(properties) — Sets properties only if not already set. Use for immutable attributes.

See also