> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Heap

<!-- -->

[Web](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/heap)

<!-- -->

[Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/heap)[ ](https://www.npmjs.com/package/@walkeros/web-destination-heap)

<!-- -->

[Package](https://www.npmjs.com/package/@walkeros/web-destination-heap)

<!-- -->

Beta

[Heap](https://www.heap.io/) (now part of Contentsquare) is a product analytics platform with auto-capture and retroactive event definitions. This destination loads the Heap snippet from Heap's CDN and forwards walkerOS events through `heap.track(name, properties)`, plus identity, user properties, persistent event properties, and runtime consent.

<!-- -->

Where this fits

Heap is a **web destination** in the walkerOS flow:

## Installation[​](#installation "Direct link to Installation")

```
npm install @walkeros/web-destination-heap
```

* Integrated
* Bundled

```
import { startFlow } from '@walkeros/collector';
import { destinationHeap } from '@walkeros/web-destination-heap';

await startFlow({
  destinations: {
    heap: {
      code: destinationHeap,
      config: {
        loadScript: true,
        settings: {
          appId: 'YOUR_HEAP_APP_ID',
        },
      },
    },
  },
});
```

Add to your `flow.json` destinations:

```
"destinations": {
  "heap": {
    "package": "@walkeros/web-destination-heap",
    "config": {
      "loadScript": true,
      "settings": {
        "appId": "YOUR_HEAP_APP_ID"
      }
    }
  }
}
```

[See bundled mode setup](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md)

## Configuration[​](#configuration "Direct link to Configuration")

This <!-- -->destination<!-- --> uses the standard <!-- -->destination<!-- --> config wrapper (consent, data, env, id, ...). For the shared fields see [destination<!-- --> configuration](https://www.walkeros.io/docs/destinations.md#configuration). Package-specific fields live under `config.settings` and are listed below.

## Settings[​](#settings "Direct link to Settings")

| Property                     | Type      | Description                                                                                                                              | More |
| ---------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `appId*`                     | `string`  | Heap App ID. Find it in your Heap project under Settings > App ID.                                                                       |      |
| `disableTextCapture`         | `boolean` | Disable Heap auto text capture. Default: true.                                                                                           |      |
| `disablePageviewAutocapture` | `boolean` | Disable Heap automatic pageview tracking. Default: true (walkerOS sources handle pageviews).                                             |      |
| `disableSessionReplay`       | `boolean` | Disable Heap session replay.                                                                                                             |      |
| `secureCookie`               | `boolean` | SSL-only cookies.                                                                                                                        |      |
| `ingestServer`               | `string`  | Custom server endpoint for proxying Heap data.                                                                                           |      |
| `identify`                   | `any`     | Destination-level identity mapping. Resolves to a string for heap.identify(). Example: { "key": "user.id" }.                             |      |
| `userProperties`             | `any`     | Destination-level user properties mapping. Resolves to object for heap.addUserProperties(). Example: { "map": { "plan": "data.plan" } }. |      |

\* Required fields

## Mapping[​](#mapping "Direct link to Mapping")

Per-event rules under `config.mapping`. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md).

| Property               | Type  | Description                                                                                                            | More |
| ---------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------- | ---- |
| `identify`             | `any` | Per-event identity. Resolves to a string for heap.identify(). Example: { "key": "data.email" }.                        |      |
| `reset`                | `any` | Reset Heap identity on this event. Set to true to call heap.resetIdentity().                                           |      |
| `userProperties`       | `any` | Per-event user properties. Resolves to object for heap.addUserProperties().                                            |      |
| `eventProperties`      | `any` | Per-event persistent event properties. Resolves to object for heap.addEventProperties() (persisted across page loads). |      |
| `clearEventProperties` | `any` | Clear all persistent event properties. Set to true to call heap.clearEventProperties().                                |      |

## Examples

### Consent granted

A walker consent grant for analytics calls heap.startTracking to resume event capture.

Event

```
{
  "analytics": true
}
```

Out

```
heap.startTracking()
```

### Consent revoked

After analytics consent is granted (Heap loads and starts tracking), revoking it calls heap.stopTracking to pause event capture.

Event

```
{
  "analytics": false
}
```

Out

```
heap.startTracking();

heap.stopTracking()
```

### Default track

A walker event becomes a Heap track call with the event name and empty properties.

Event

```
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "5d966dceb6b578a6",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000100,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```
heap.track("product view", {})
```

### Destination identify

Destination-level identify calls heap.identify with the user id before firing the default track.

Event

```
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "25cd68b15e54c18f",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000102,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```
heap.identify("us3r");

heap.track("page view", {})
```

### Renamed purchase

An order complete is renamed to purchase and mapped to Heap track properties such as order\_id, total, and currency.

Event

```
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "900f98b30778e1af",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000101,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "purchase",
  "data": {
    "map": {
      "order_id": "data.id",
      "total": "data.total",
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      }
    }
  }
}
```

Out

```
heap.track("purchase", {
  "order_id": "0rd3r1d",
  "total": 555,
  "currency": "EUR"
})
```

### User properties on event

An order fires Heap addUserProperties with last-order fields and then tracks the event.

Event

```
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "total": 555,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "139e6558cd4db528",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000105,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "settings": {
    "userProperties": {
      "map": {
        "last_order_value": "data.total",
        "last_order_currency": "data.currency"
      }
    }
  }
}
```

Out

```
heap.addUserProperties({
  "last_order_value": 555,
  "last_order_currency": "EUR"
});

heap.track("order complete", {})
```

### Global event properties

A page view sets persistent Heap event properties so all subsequent events include the page category.

Event

```
{
  "name": "page view",
  "data": {
    "category": "docs"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "77ebb438ab046b09",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000106,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "silent": true,
  "settings": {
    "eventProperties": {
      "map": {
        "page_category": "data.category"
      }
    }
  }
}
```

Out

```
heap.addEventProperties({
  "page_category": "docs"
})
```

### User login identify

A user login identifies the Heap user by email and adds user properties while skipping the track.

Event

```
{
  "name": "user login",
  "data": {
    "email": "user@example.com",
    "plan": "premium",
    "company": "Acme"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "fee238a5d66ad661",
  "trigger": "test",
  "entity": "user",
  "action": "login",
  "timestamp": 1700000103,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "silent": true,
  "settings": {
    "identify": "data.email",
    "userProperties": {
      "map": {
        "plan": "data.plan",
        "company": "data.company"
      }
    }
  }
}
```

Out

```
heap.identify("user@example.com");

heap.addUserProperties({
  "plan": "premium",
  "company": "Acme"
})
```

### User logout reset

A user logout calls heap.resetIdentity to clear the identified user from the Heap client.

Event

```
{
  "name": "user logout",
  "data": {
    "string": "foo",
    "number": 1,
    "boolean": true,
    "array": [
      0,
      "text",
      false
    ]
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "57dbc7e5e2be4daf",
  "trigger": "test",
  "entity": "user",
  "action": "logout",
  "timestamp": 1700000104,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "silent": true,
  "settings": {
    "reset": true
  }
}
```

Out

```
heap.resetIdentity()
```

## Consent[​](#consent "Direct link to Consent")

The destination wires walkerOS `config.consent` to Heap's runtime consent API. `heap.startTracking()` fires when all required consent keys are granted; `heap.stopTracking()` fires otherwise.

```
destinations: {
  heap: {
    code: destinationHeap,
    config: {
      consent: { analytics: true },
      settings: { appId: 'YOUR_HEAP_APP_ID' },
    },
  },
}
```