Heap sideloading (legacy)

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.

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.

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 to get the correct directives.

In sideloading mode the following commands wrap their Heap SDK equivalents. The signatures are the same as those documented in the Tag API reference, with the differences listed here.

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

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.

The { hash: true } option documented for 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.

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

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.

Avoid arbitrary setTimeout workarounds. Use afterPageView instead: the callback runs after the Tag's initial bootstrap, so window.heap is defined.

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]);
  },
]);

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.