> ## Documentation Index
> Fetch the complete documentation index at: https://subtext.fullstory.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Identify Users in Your Subtext Sessions

> Attach a stable user ID and user properties to a session with FS('setIdentity') so you can find and filter sessions by the person they belong to.

A session is far more useful when it is tied to a specific user. Call `FS('setIdentity')` to attach a stable user ID and any user properties you want to filter by, so you can locate a session by who it belongs to instead of searching through anonymous traffic. Use it once you know who the current user is.

```js theme={null}
FS('setIdentity', {
  uid: '<STABLE_INTERNAL_USER_ID>',
  properties: {
    displayName: 'Ada Lovelace',
    email: 'ada@example.com',
    // any custom user properties already available on the client
    plan: 'pro',
    createdAt: '2024-08-12T00:00:00Z',
  },
})
```

## Rules

* `uid` MUST be a stable internal id, not an email. Emails change; ids should not.
* Call `setIdentity` only for authenticated users. Do not call it for anonymous visitors.
* Use whatever the app already has on the client. Do not introduce new server fetches just to populate properties.

## React lifecycle

<Warning>
  In React-based apps, you MUST call `setIdentity` inside a `useEffect` that fires when the authenticated user changes. Do not call it on every render, and do not call it at module top level.
</Warning>

```tsx theme={null}
import { useEffect } from 'react'

function useFullStoryIdentity(user: User | null) {
  useEffect(() => {
    if (!user) return
    FS('setIdentity', {
      uid: user.id,
      properties: {
        displayName: user.name,
        email: user.email,
      },
    })
  }, [user])
}
```

Place the hook below your auth provider so `user` is populated. Use the user (or just the user id) as the dependency array, not an empty array, so re-identifying after login resolution works.

## Why the lifecycle matters

* **Top-level calls** fire before auth has resolved, so `uid` is `undefined` and the call is wasted.
* **Calls on every render** spam the queue and can clobber properties set by other code paths.
* **Calls inside an effect with `[]`** only fire on first mount, missing later auth resolution.

## Non-React entry points

For vanilla JS, plain HTML, or non-React frameworks, call `setIdentity` from whatever lifecycle hook fires once auth has resolved: an auth provider callback, a login success handler, or a session bootstrap.

## See also

* [Get session URL](/docs/api/get-session) for linking the session URL into other tools after identification.