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

# Identity tracking

> Associate visualizations with customer identities across sessions

# Identity tracking

Selektable automatically tracks visitors using browser storage. You can optionally associate visitors with known user identities for better analytics and cross-device tracking.

## Automatic tracking

The embed script automatically generates and manages:

| ID               | Storage          | Scope       | Description                                                |
| ---------------- | ---------------- | ----------- | ---------------------------------------------------------- |
| **Visitor ID**   | `localStorage`   | Persistent  | Unique identifier for the browser, survives tab closes     |
| **Session ID**   | `sessionStorage` | Tab/session | Resets when the tab is closed                              |
| **Anonymous ID** | `localStorage`   | Persistent  | Initially same as visitor ID, preserved after `identify()` |

These IDs are automatically included in all widget API calls without any configuration needed.

## Identifying known users

When a customer logs into your site, call `identify()` to associate their visitor ID with their user account:

```javascript theme={null}
// After user login or on page load with authenticated user
Selektable.identify('user-123', {
  name: 'John Doe',
  email: 'john@example.com'
});
```

**Parameters:**

| Parameter | Type     | Description                                     |
| --------- | -------- | ----------------------------------------------- |
| `userId`  | `string` | Your system's user ID                           |
| `traits`  | `object` | Optional key-value metadata (name, email, etc.) |

This does three things:

1. Stores the user ID and traits in the browser
2. Sends the identity to the Selektable server in the background
3. Updates all currently open widgets with the new identity

## Resetting identity

When a user logs out, reset the identity to generate a new anonymous visitor:

```javascript theme={null}
// On logout
Selektable.reset();
```

This generates new visitor, session, and anonymous IDs. The previous user association is cleared.

## Reading the current identity

```javascript theme={null}
const identity = Selektable.getIdentity();

console.log(identity);
// {
//   visitorId: 'abc123...',
//   sessionId: 'def456...',
//   anonymousId: 'abc123...',
//   userId: 'user-123',          // undefined if not identified
//   traits: { name: 'John Doe' } // undefined if not set
// }
```

## Setting a custom visitor ID

If you have your own visitor tracking system, you can override the auto-generated visitor ID:

```javascript theme={null}
Selektable.setVisitorId('my-custom-visitor-id');
```

<Warning>
  Only use this if you have a specific reason to manage visitor IDs yourself. The auto-generated IDs work well for most use cases.
</Warning>

## Privacy considerations

* All IDs are generated client-side in the browser
* No cookies are used
* Calling `Selektable.reset()` clears all stored identity data
* If `localStorage` is unavailable (e.g., private browsing), ephemeral IDs are generated per page load