## How the Heap integration works

Enabling the Heap integration allows you to export Statsig events to your configured Heap app with information on the status of each user's feature gate and experimentation groups.

Statsig sends events to Heap when a client SDK is initialized, and also forwards events as they are received.

## Client SDK initialize events

Statsig sends the following events to your Heap app every time you call the `initialize` API from a Statsig client SDK.

| Event Name            | Properties                                                                                                                                                                                                                   |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Statsig Feature Gates | For each [Statsig Feature Gate](/feature-flags/overview), this field contains a property that maps the name of the feature gate to `true` or `false`, stating whether the user passes or does not pass the feature gate. |
| Statsig Experiments   | For each [Statsig Experiment](/experiments/overview), this field contains a property that maps the name of the experiment to the variant that the user is assigned to.                                                           |

## Exposures and custom event forwarding

Statsig can forward events as they are received from SDKs, Integrations or the HTTP API.

Events include exposures (Gate, Experiment, Config) and custom events.

### Event format

Events are sent in batches in JSON format. Each Statsig event has the following structure:

| Field           | Type   | Description                                                          |
| --------------- | ------ | -------------------------------------------------------------------- |
| eventName       | String | Name of the event provided                                           |
| user            | JSON   | [Statsig User Object](/sdks/user) |
| userID          | String | User ID provided                                                     |
| timestamp       | Number | Timestamp in MS of the event                                         |
| value           | String | Value of the event provided                                          |
| metadata        | JSON   | Custom Metadata provided                                             |
| statsigMetadata | JSON   | Metadata related to the logging of this event added by Statsig       |
| timeUUID        | String | UUID for the event                                                   |
| unitID          | String | Unit ID of the exposure (e.g. userID, stableID, or the customID)     |

#### Custom event formatting - logEvent

>

```json
{
  "eventName": "my_custom_event",
  "user": {
    "userID": "a_user",
    "email": "a.user@email.com"
  },
  "userID": "a_user",
  "timestamp": "1655231253265",
  "statsigMetadata": {
    ...
  },
  "value": "a_custom_value",
  "metadata": {
    "key_a": "value_a",
    "key_b": "123"
  },
  "timeUUID": "abd2a983-ec0f-11ec-917a-fb8cdaeda578"
}
```

#### Feature gate exposure formatting - checkGate

>

```json
{
  "eventName": "statsig::gate_exposure",
  "user": { ... },
  "userID": "a_user",
  "timestamp": "1655231253265",
  "statsigMetadata": { ... },
  "value": "",
  "metadata": {
    "gate": "a_gate",
    "gateValue": "false",
    "ruleID": "default",
    "reason": "Network",
    "time": "1655231249644"
  },
  "timeUUID": "8d7c1040-ec11-11ec-g123-abe2c32fcf46",
  "unitID": "userID"
}
```

#### Dynamic config exposure formatting - getConfig

>

```json
{
  "eventName": "statsig::config_exposure",
  "user": { ... },
  "userID": "a_user",
  "timestamp": "1655231253265",
  "statsigMetadata": { ... },
  "value": "",
  "metadata": {
    "config": "a_config",
    "ruleID": "default",
    "reason": "Network",
    "time": "1655231249644"
  },
  "timeUUID": "af379f60-ec11-22ad-8e0a-05c3ee70bd0c",
  "unitID": "userID"
}
```

#### Experiment exposure formatting - getExperiment

>

```json
{
  "eventName": "statsig::experiment_exposure",
  "user": { ... },
  "userID": "a_user",
  "timestamp": "1655232119734",
  "statsigMetadata": { ... },
  "value": "",
  "metadata": {
    "config": "an_experiment",
    "ruleID": "4SauZJcM1T7zNvh1igBjwE",
    "reason": "Network",
    "time": "1655231249644",
    "experimentGroupName": "Control"
  },
  "timeUUID": "af379f61-ab22-11ec-8e0a-05c3ee70bd0c",
  "unitID": "userID"
}
```

#### Example batch

>

```json
[
  {
    "eventName": "page_view",
    "user": {"userID": "user_1", "country": "US"},
    "userID": "user_1",
    "timestamp": 1644520566967,
    "value": "example_value",
    "metadata": {"page": "home_page"},
    "statsigMetadata": {},
    "timeUUID": "f4c414a0-8ab5-11ec-a8a3-0242ac120002"
  },
  {
    "eventName": "statsig::gate_exposure",
    "user": {"userID": "user_1", "country": "US"},
    "userID": "user_1",
    "timestamp": 1644520566968,
    "value": "",
    "metadata": {"gate": "test_gate", "gateValue": "true", "ruleID": "default"},
    "statsigMetadata": {},
    "timeUUID": "f4c414a0-8ab5-11ec-a8a3-0242ac120003",
    "unitID": "userID"
  },
  {
    "eventName": "statsig::experiment_exposure"
    "user": {"userID": "user_1", "country": "US"},
    "userID": "user_1",
    "timestamp": 1644520566969,
    "value": "",
    "metadata": {
       "config": "an_experiment", "ruleID": "4SauZJcM1T7zNvh1igBjwE", "reason": "Network", "time": "1655231249644", "experimentGroupName": "Control"
    },
    "statsigMetadata": {},
    "timeUUID": "f4c414a0-8ab5-11ec-a8a3-0242ac120004",
    "unitID": "userID"
  }
]
```

## Configuring outbound events

1. Navigate to your [Heap Projects](https://heapanalytics.com/app/manage/projects) page to find and copy the App ID for your project.

{% figure %}
![Heap projects page showing App ID value to copy](/images/integrations/data-connectors/heap/outgoing_1.png)
{% /figure %}

2. Paste the App ID into the App ID input field for the Heap configuration in the Statsig [Integrations](https://console.statsig.com/integrations) page and save your changes.

## First exposures

[First exposures](/experiments/interpreting-results/export#first-exposures-file-description) are an enterprise-tier feature that simplifies your project insights.

{% callout type="info" %}
This is available for Enterprise contracts. Reach out to the support team, your sales contact, or through the [Slack community](https://statsig.com/slack) if you want this enabled.
{% /callout %}

### How first exposures work

The Heap integration can forward first exposures instead of every exposure, reducing the total number of events forwarded. First exposures are calculated daily and forwarded to integrations at around 7pm UTC.

### Enable first exposures

Ensure the "first exposure" feature has been enabled for your company by contacting the support team, your sales contact, or the [Slack community](https://statsig.com/slack). Then go to the event filtering tab of the integration and enable the **First Exposure** setting.