@thg-altitude/insights v0.2.4

A flexible analytics and tracking package for THG Commerce applications. This package provides tracking capabilities for various frameworks including Astro, Next.js, and React Native.

Features

• Track page views automatically
• Track impressions using IntersectionObserver
• Track clicks using event delegation
• Send data asynchronously using the Beacon API
• Support for multiple frameworks (Astro, Next.js, React Native)
• Simple and DRY implementation

Installation

npm install @thg-commerce/insights

Usage

Core Usage

The core module can be used directly in any JavaScript application:

import insights from "@thg-commerce/insights/core";

// Initialize the tracker
insights.init({
  endpoint: "https://analytics-api.example.com",
  clientId: "beauty-storefront",
  debug: false,
});

// Track an impression programmatically
insights.trackImpression({
  category: "widget",
  id: "featured-products",
});

// Track a click programmatically
insights.trackClick({
  category: "button",
  id: "add-to-cart",
});

// Simplified tracking
insights.track("widget:featured-products");

HTML Data Attributes

You can use data attributes to track elements without writing JavaScript:

<!-- Track an impression -->
<div
  data-insights-category="widget"
  data-insights-id="featured-products"
  data-insights-position="top"
  data-insights-variant="large"
>
  <!-- Widget content -->
</div>

<!-- Track a click -->
<button
  data-insights-category="button"
  data-insights-id="add-to-cart"
  data-insights-variant="primary"
  data-insights-size="large"
>
  Add to Cart
</button>

Astro Integration

// astro.config.mjs
import { defineConfig } from "astro/config";
import insights from "@thg-commerce/insights/astro";

export default defineConfig({
  integrations: [
    insights({
      endpoint: "https://analytics-api.example.com",
      clientId: "beauty-storefront",
      debug: false,
    }),
  ],
});

Next.js Middleware

// middleware.js
import { insightsMiddleware } from "@thg-commerce/insights/next";

export default insightsMiddleware({
  endpoint: "https://analytics-api.example.com",
  clientId: "beauty-storefront",
  debug: false,
});

export const config = {
  matcher: "/((?!api|_next/static|favicon.ico).*)",
};

React Native

import React, { useEffect } from "react";
import { View, Text, Button } from "react-native";
import {
  initializeInsights,
  trackScreen,
  trackEvent,
  cleanup,
} from "@thg-altitude/insights/react-native";

function App() {
  useEffect(() => {
    // Initialize the tracker
    initializeInsights({
      endpoint: "https://analytics-api.example.com",
      clientId: "beauty-storefront-app",
      debug: false,
    });

    // Track the current screen
    trackScreen("HomeScreen", {
      category: "screen",
      id: "home",
    });

    // Clean up on unmount
    return () => {
      cleanup();
    };
  }, []);

  const handleButtonPress = () => {
    // Track a button press
    trackEvent({
      category: "button",
      id: "add-to-cart",
      variant: "primary",
    });
  };

  return (
    <View>
      <Text>Home Screen</Text>
      <Button title="Add to Cart" onPress={handleButtonPress} />
    </View>
  );
}

export default App;

Event Payload

The package sends a single page_view event with a stream of interactions:

{
  "type": "page_view",
  "path": "/c/example",
  "client_id": "beauty-storefront",
  "stream": [
    {
      "category": "widget",
      "type": "impression",
      "id": "featured-products",
      "position": 1,
      "position": "top",
      "variant": "large"
    },
    {
      "category": "button",
      "type": "click",
      "id": "add-to-cart",
      "position": 2,
      "variant": "primary",
      "size": "large"
    }
  ]
}

Configuration Options

Validating Beacon Sending

To validate that the beacon is sending data correctly:

1. Using Browser Developer Tools

1. Open your application in Chrome or Firefox
2. Open Developer Tools (F12 or Right-click > Inspect)
3. Go to the Network tab
4. Navigate away from the page (or trigger a visibility change)
5. Look for a POST request to your endpoint

In Chrome, you can filter for beacon requests by typing "beacon" in the filter box.

2. Enable Debug Mode

Enable debug mode in your configuration:

insights.init({
  endpoint: "https://analytics-api.example.com",
  clientId: "test-client",
  debug: true, // Enable debug mode
});

With debug mode enabled, the package will log all tracking activities to the console, including when data is sent via beacon.

Examples

This package includes examples to help you get started:

• Astro with Cloudflare - Example of using the package with Astro and the Cloudflare adapter

Browser Compatibility

The package uses modern browser APIs like IntersectionObserver and Navigator.sendBeacon. For older browsers, it falls back to more compatible approaches when possible.

License

MIT