> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/en/getting-started/user-identifier/session-management.md).

# Session Management

A Session represents a continuous period of app usage by a user, and it starts and expires based on specific conditions.

### Session Start Conditions

A session starts under the following conditions by default.

* When the identifier changes
* When an event occurs after the session timeout period has elapsed

### Session Expiration Conditions

When a new session starts, the previous session expires.

* The session expiration time equals the time of the last event.

### Session Policy

The Session Policy is a feature that allows fine-grained control over session persistence and expiration conditions. A Session Policy consists of two types of conditions.

#### Persist Condition

Determines whether to maintain the existing session or start a new one when the identifier changes.

| Option           | Default | Description                                                                                                                                          |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| alwaysNewSession | default | Always starts a new session when the identifier changes.                                                                                             |
| nullToUserId     |         | Keeps the existing session when userId changes from null to a specific value (i.e., on login). Starts a new session for any other identifier change. |

#### Timeout Condition

Configures the conditions under which a session expires.

| Setting                  | Default               | Description                                                                  |
| ------------------------ | --------------------- | ---------------------------------------------------------------------------- |
| timeout                  | 1800 seconds (30 min) | The session timeout duration.                                                |
| onForeground             | false                 | Whether to check the timeout when an event occurs in the foreground.         |
| onBackground             | true                  | Whether to check the timeout when an event occurs in the background.         |
| onApplicationStateChange | true                  | Checks the timeout when the app state changes (`foreground <-> background`). |

{% hint style="info" %}
For specific configuration code for the Session Policy, refer to the SDK integration documentation for each SDK.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hackle.io/en/getting-started/user-identifier/session-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.