People

This module is used to identify users and mutate user profile properties (set, set once, append, increment, delete).

Available at:

tracker.analytics.people

Top-level alias: tracker.analytics.identify(...) → same as tracker.analytics.people.identify(...)

// Identify a user (required before other operations except reset)
tracker.analytics.people.identify(user_id: string, options?: { fromTracker: boolean }): void

// Reset local user context & properties (optionally, destroy device id)
// should be called on logout and session end
tracker.analytics.people.reset(hard?: boolean): void

// Delete user on backend, then reset local properties
tracker.analytics.people.deleteUser(): void

// Set properties (overwrite existing values)
tracker.analytics.people.setProperties(properties: Record<string, string | number>): void
tracker.analytics.people.setProperties(key: string, value: string | number): void

// Set properties only if they don't exist yet
tracker.analytics.people.setPropertiesOnce(properties: Record<string, string | number>): void

// Append values to an existing property (string becomes array)
tracker.analytics.people.appendValues(key: string, value: string | number): void

// Append value only if it’s not already present (requires property to exist locally)
tracker.analytics.people.appendUniqueValues(key: string, value: string | number): void

// Increment (or decrement) a numeric property
tracker.analytics.people.increment(key: string, value: number): void

// Read current user id
tracker.analytics.people.user_id: string | null | undefined

Identifies the current user by a string id (email, username, internal id, etc.) and queues an identity event.

tracker.analytics.people.identify("nikita@openreplay.com")

If a different user was already identified, the SDK resets local people properties before switching to the new id.

options.fromTracker is used internally to avoid double-calling the tracker-level id hook; you typically don’t need it.

Resets the current user id and all local people properties.

// soft reset
tracker.analytics.people.reset()

// hard reset (also clears persistent device id)
tracker.analytics.people.reset(true)

Deletes the currently identified user on the backend (by sending a delete mutation), then clears local state.

tracker.analytics.people.deleteUser()

If no user is identified, it’s a no-op.

After calling this, user_id will be cleared and local properties are wiped.

Sets user properties, overwriting existing values.

tracker.analytics.people.setProperties({
	plan: "pro",
	seats: 5,
})

// or key/value
tracker.analytics.people.setProperties("plan", "enterprise")

Reserved/default keys (internal tracker keys) are ignored for the SDK’s local cache.

An event is queued with the full properties payload you pass.

Sets properties only if they don’t exist yet (from the SDK’s local perspective).

tracker.analytics.people.setPropertiesOnce({
	signup_source: "docs",
	first_seen_at: Date.now(),
})

Only properties not already present in the local people cache will be written locally.

A setPropertyOnce mutation event is still queued with the properties you pass.

Appends a value to an existing property. If the property is currently a string/number, it becomes an array.

// start with something
tracker.analytics.people.setProperties({ tags: "new" })

// append
tracker.analytics.people.appendValues("tags", "beta-user")

The SDK only updates the local cache if that property already exists locally.

An append mutation event is always queued.

Appends a value only if it’s not already present.

tracker.analytics.people.setProperties({ tags: ["new"] })
tracker.analytics.people.appendUniqueValues("tags", "new") // no change
tracker.analytics.people.appendUniqueValues("tags", "beta-user") // appended

If the property does not exist locally yet, this call does nothing (returns early). Set it first via setProperties / setPropertiesOnce.

Adds a number (including negative values) to a numeric property.

tracker.analytics.people.increment("logins", 1)
tracker.analytics.people.increment("credits", -10)

If the property doesn’t exist locally, it’s initialized to 0 before incrementing.

If the property exists but is not numeric, the SDK throws an error.

All methods support compatibility layer provided for familiarity:

tracker.analytics.people.set // setProperties
tracker.analytics.people.set_once // setPropertiesOnce
tracker.analytics.people.append // appendValues
tracker.analytics.people.union // appendUniqueValues
tracker.analytics.people.incrementBy // increment

Typical flow

tracker.analytics.people.identify("user_123")

tracker.analytics.people.setProperties({
	email: "user@example.com",
	plan: "pro",
})

tracker.analytics.people.increment("sessions", 1)
tracker.analytics.people.appendUniqueValues("features_used", "analytics")

Keep in mind, that OpenReplay sessions only support single user as of 1.24.0, which means new user overwrites the previous one in the session. When switching users, restart the tracker with forceNew option as well.

tracker.analytics.people.identify("user_a")
tracker.analytics.people.setProperties({ plan: "free" })

// switching user resets local people properties automatically
tracker.analytics.people.identify("user_b")

If you encounter any issues, connect to our Slack or check out our Forum and get help from our community.