---
title: Heap sideloading (legacy) - Web
description: Reference for projects where the Contentsquare Tag loads the Heap SDK, and how the Product Analytics commands differ in that mode
source_url:
  html: https://docs.contentsquare.com/fr/web/heap-sideloading/
  md: https://docs.contentsquare.com/fr/web/heap-sideloading/index.md
---

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

Note

Cette page est affichée en anglais car elle n'est pas disponible dans votre langue.

Legacy mode

Heap sideloading is no longer offered for new implementations. New projects collect Product Analytics data natively — see [Product Analytics](https://docs.contentsquare.com/en/web/product-analytics/) and the [Tag API reference](https://docs.contentsquare.com/en/web/command-reference/).

Existing sideloaded projects are covered here, and only here: everywhere else in these docs, Product Analytics commands are described for native collection.

In sideloading mode, the Contentsquare Tag injects the Heap SDK (`heap.js`) into the page and the Product Analytics Tag commands act as thin wrappers around the equivalent `heap.*` calls. Data is collected and sent by the Heap SDK, not by the Contentsquare Tag.

In native collection, no Heap SDK is loaded: the Contentsquare Tag collects Product Analytics data itself and sends it with its own requests.

## Identifying the mode

A sideloaded project sends `cw=2` on its pageview requests, and `window.heap` is defined on the page. A natively collecting project sends `cw=1` and does not define `window.heap`.

## Content Security Policy

Because the Tag loads an additional script and that script sends its own requests, sideloading requires CSP directives beyond those needed for native collection. Select the matching mode in the builder on [Content Security Policy](https://docs.contentsquare.com/en/web/content-security-policy/) to get the correct directives.

## Command behavior

In sideloading mode the following commands wrap their Heap SDK equivalents. The signatures are the same as those documented in the [Tag API reference](https://docs.contentsquare.com/en/web/command-reference/), with the differences listed here.

| Command | Wraps | Heap reference | Available since |
| - | - | - | - |
| [`trackEvent`](https://docs.contentsquare.com/en/web/command-reference/#trackevent) | `heap.track` | [`track` ↗](https://developers.heap.io/reference/track) | `15.247.0` |
| [`identify`](https://docs.contentsquare.com/en/web/command-reference/#identify) | `heap.identify` | [`identify` ↗](https://developers.heap.io/reference/identify) | `15.1.0` |
| [`resetIdentity`](https://docs.contentsquare.com/en/web/command-reference/#resetidentity) | `heap.resetIdentity` | [`resetIdentity` ↗](https://developers.heap.io/reference/resetidentity) | `15.1.0` |
| [`getIdentity`](https://docs.contentsquare.com/en/web/command-reference/#getidentity) | `heap.getIdentity` | [`getIdentity` ↗](https://developers.heap.io/docs/api-reference#getidentity) | `15.1.0` |
| [`addUserProperties`](https://docs.contentsquare.com/en/web/command-reference/#adduserproperties) | `heap.addUserProperties` | [`addUserProperties` ↗](https://developers.heap.io/reference/adduserproperties) | `15.31.0` |
| [`customProperties:visit:add`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitadd) | `heap.addEventProperties` | [`addEventProperties` ↗](https://developers.heap.io/reference/addeventproperties) | `15.152.0` |
| [`customProperties:visit:remove`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitremove) | `heap.removeEventProperty` | [`removeEventProperty` ↗](https://developers.heap.io/reference/removeeventproperty) | `15.152.0` |
| [`customProperties:visit:clear`](https://docs.contentsquare.com/en/web/command-reference/#custompropertiesvisitclear) | `heap.clearEventProperties` | [`clearEventProperties` ↗](https://developers.heap.io/reference/cleareventproperties) | `15.152.0` |

All of these commands support iframes (iframe). None of them support webviews in this mode.

### Commands not available

Pageview property commands (`customProperties:page:add`, `customProperties:page:remove`, and `customProperties:page:clear`) have no Heap SDK equivalent and are not available in sideloading mode.

### `identify` does not accept hashing options

The `{ hash: true }` option documented for [`identify`](https://docs.contentsquare.com/en/web/command-reference/#identify) is not supported: the command passes the identity string straight to `heap.identify()`. Hash the identifier yourself before calling the command if you need it hashed.

```javascript
window._uxa.push(["identify", identityString]);
```

### `getIdentity` returns the Heap identity

`getIdentity` forwards to `heap.getIdentity()` and returns whatever the Heap SDK holds. In native collection, the command returns a hash of the identity string rather than the string itself.

### Call `identify` after the Tag has initialized

Attention

`identify` requires `window.heap` to be defined. Commands pre-loaded into `_uxa` before the Tag script runs are replayed as soon as the Tag bootstraps, but the sideloading module initializes slightly later, so `window.heap` may not be ready yet. Calling `identify` at that point silently does nothing.

Avoid arbitrary `setTimeout` workarounds. Use [`afterPageView`](https://docs.contentsquare.com/en/web/command-reference/#afterpageview) instead: the callback runs after the Tag's initial bootstrap, so `window.heap` is defined.

```javascript
window._uxa.push([
  "afterPageView",
  function (context) {
    // Only run on natural pageviews, not artificial or renewal ones
    if (context.pageViewType !== "n") return;


    window._uxa.push(["identify", identityString]);
  },
]);
```

## Migrating to native collection

Native collection removes the second SDK from the page, supports webviews, adds pageview properties, and simplifies your CSP. Contact your Customer Success Manager to plan the migration.


```json
{"@context":"https://schema.org","@type":"TechArticle","headline":"Heap sideloading (legacy)","description":"Reference for projects where the Contentsquare Tag loads the Heap SDK, and how the Product Analytics commands differ in that mode","url":"https://docs.contentsquare.com/fr/web/heap-sideloading/","inLanguage":"en","dateModified":"2026-10-02T16:39:51+02:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Documentation technique Contentsquare","url":"https://docs.contentsquare.com/"}}
```