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

# Flutter SDK

> Hightouch's Flutter SDK for collecting events

The Flutter SDK makes it easy to track events from all types of Flutter applications.

## Installation

The Flutter SDK is hosted on [pub.dev](https://pub.dev/packages/hightouch_events).

You may install the SDK by adding it to your `pubspec.yaml` file:

```sh theme={null}
flutter pub add hightouch_events
```

## Initialization

You should initialize the SDK in the top-level app state and store it in a variable
for use across your application. For example, you may want to initialize it in
your app delegate.

**Example**:

```
final analytics = createClient(Configuration("WRITE_KEY"));
```

**Configuration options**:

| Option | Type | Description |
| - | - | - |
| `writeKey` | String | Your Hightouch write key. |
| `apiHost` | String | The API host to send the tracked events to. |
| `trackApplicationLifecycleEvents` | Bool | Whether to automatically track application lifecycle events (like opening the application). Defaults to `false`. |
| `foregroundSessionTimeout` | int | Maximum foreground inactivity in milliseconds before a new session starts. Defaults to `1800000` (30 minutes). |
| `backgroundSessionTimeout` | int | Maximum time in the background, in milliseconds, before a new session starts on resume. Defaults to `1800000` (30 minutes). |

## Session tracking

Session tracking is enabled by default. The SDK attaches `sessionId`, `sessionStart`, and a `session` object to `context` on every event so you can group events from the same app session.

Sessions use two timeouts, both in milliseconds:

* `foregroundSessionTimeout` limits inactivity while the app is in the foreground.
* `backgroundSessionTimeout` limits how long the app can stay in the background before the next resume starts a new session.

Both default to `1800000` (30 minutes). Set both to `0` to disable session tracking.

A new session starts when any of these occur:

* First launch, when no session state is persisted.
* Foreground inactivity exceeds `foregroundSessionTimeout`.
* Resume after being backgrounded longer than `backgroundSessionTimeout`, including after process death.
* Calling `reset()`.

Session state is persisted across app relaunches. `sessionIndex` is a per-device lifetime counter. It starts at `0` and resets only when the app is uninstalled, not when you call `reset()`.

You can change the timeouts when you initialize the SDK:

```
final analytics = createClient(Configuration("WRITE_KEY",
    foregroundSessionTimeout: 60 * 60 * 1000,
    backgroundSessionTimeout: 60 * 60 * 1000));
```

`context.session` includes:

| Field | Type | Description |
| - | - | - |
| `sessionId` | int | Current session ID (epoch milliseconds). |
| `sessionIndex` | int | Per-device lifetime counter. Starts at `0`. |
| `sessionStart` | boolean | Present and `true` only on the first event of the session. |
| `eventIndex` | int | 0-based index of the event within the session. |
| `previousSessionId` | int or null | Previous session ID. `null` on the first session. |
| `firstEventId` | UUID | `messageId` of the session's first event. |
| `firstEventTimestamp` | ISO 8601 | When the session began. |

`sessionId` and `sessionStart` are also set on `context` for parity with the [browser SDK](https://docs.hightouch.com/events/sdks/browser.md#session-tracking). `sessionStart` is included only when it is `true`.

## API

### Identify

The `analytics.identify` method sends an [`identify`](https://docs.hightouch.com/events/event-spec#identify-events) event.

**Example usage**:

```
analytics.identify(userId: "user-123", userTraits: UserTraits(email: "user@example.com"));
```

### Track

The `analytics.track` method sends a [`track`](https://docs.hightouch.com/events/event-spec#track-events) event.

**Example usage**:

```
analytics.track("View Product", properties: {"productId": 123});
```

### Screen

The `analytics.screen` method sends a [`screen`](https://docs.hightouch.com/events/event-spec#screen-events) event.

**Example usage**:

```
analytics.screen("Home");
```

### Group

The `analytics.group` method sends a [`group`](https://docs.hightouch.com/events/event-spec#group-events) event.

**Example usage**:

```
analytics.group("group-123", groupTraits: GroupTraits(name: "Group 123"));
```

### Flush

The Flutter SDK buffers events locally before sending them to Hightouch's servers.
This minimizes the number of requests made by the SDK and makes the tracking
non-blocking.

To force the local buffer to be sent to Hightouch immediately call the `flush()`
method.

### Reset

The `reset` method resets the `identify` and `group` for the local session.
Specifically, it resets the `anonymousId`, `userId`, `referrer`, and `traits`.

The `reset` method should be called when users log out. This way, if the user
logs back in with another account, the userIds and traits from the different
sessions remain separate. Calling `reset()` also starts a new analytics session.
See [Session tracking](#session-tracking).