THG Commerce THG
Altitude
Blog GitHub Go to Platform
Products
Insights

JavaScript API

Use the JavaScript API when HTML attribute tracking isn’t suitable - for example, tracking hover events, form submissions, or integrating with existing event handlers.

For most use cases, HTML attribute tracking is simpler and recommended.

API Reference

All methods are available on the global window.insights object after the script has loaded.

window.insights.event(name, data)

Track custom events programmatically.

Parameters:

  • name (string): Event type (e.g., 'hover', 'form_submit', 'video_play')
  • data (object): Event data with any custom properties

Returns: void - Event is queued for batch upload

// Track a hover event
window.insights.event("hover", {
  category: "product",
  id: "featured-product",
  price: "19.99",
});

// Track form submission
window.insights.event("form_submit", {
  category: "form",
  id: "newsletter-signup",
  success: true,
});

// Track video interaction
window.insights.event("video_play", {
  category: "video",
  id: "product-demo",
  duration: 120,
});

window.insights.impression(data)

Track impressions programmatically. Useful when HTML attributes can’t be applied.

Parameters:

  • data (object): Impression data with any custom properties

Returns: void - Event is queued for batch upload

// Track impression for dynamically loaded content
window.insights.impression({
  category: "recommendation",
  id: "similar-product-123",
  position: 3,
});

window.insights.getPageUUID()

Get the current page UUID. Useful for correlating front-end events with back-end data.

Returns: string - Current page UUID, or 'unknown' if not yet initialised

const pageUUID = window.insights.getPageUUID();
console.log("Current page UUID:", pageUUID);

window.insights.uuid

Direct access to the current page UUID as a property.

Type: string | undefined - Current page UUID, or undefined before initialisation

console.log("Page UUID:", window.insights.uuid);

Note: The .uuid property may be undefined before the SDK has initialised. Use getPageUUID() if you need a guaranteed string value (returns 'unknown' when not initialised).

Debug Mode

Enable debug logging to see tracking activity in the browser console:

localStorage.setItem('insights_debug', 'true');

Reload the page to see debug output. To disable:

localStorage.removeItem('insights_debug');

Custom Events

Track any event by defining your own event types. The event name and data structure are flexible - use whatever makes sense for your analytics needs.

// Track a hover event
window.insights.event("hover", {
  category: "product",
  id: "featured-item",
  price: "29.99",
});

Events are queued and sent automatically - no additional configuration required.

Safe Usage Pattern

Always check that the SDK has loaded before calling methods:

if (typeof window.insights !== "undefined") {
  window.insights.event("purchase", {
    category: "ecommerce",
    id: "order-123",
    value: 99.99,
  });
}

Dynamic Content

Elements added to the page after initial load are automatically detected for HTML attribute tracking. No additional JavaScript is needed for single-page applications or dynamically loaded content.

Next Steps