Analytics Events

Lightweight event-based analytics library for tracking user interactions.

Features

• Click tracking with 500ms throttle
• Hover tracking (fires after 1s threshold, reports actual duration)
• View tracking (fires after 5s visibility at 75% threshold)
• Page view tracking (fires immediately, no threshold)
• Custom event tracking via JS (no DOM element needed)
• Session tracking via sessionStorage (persists across page reloads)
• Event batching (10 events or 10s timeout, flushes on page hide)
• Custom attributes via data-analytics-*

Install

npm install @canonical/analytics-events

Usage

<button data-analytics-click data-analytics-target="signup_btn">
  Sign Up
</button>

<div data-analytics-hover data-analytics-target="promo_banner">
  Hover me
</div>

<section data-analytics-view data-analytics-target="hero_section">
  Track when this section is viewed
</section>

<script type="module">
  import { initAnalytics, trackPageView, trackEvent } from '@canonical/analytics-events';

  initAnalytics({
    appName: 'snapcraft',
    endpoint: 'https://marketplace-analytics.canonical.com/analytics/events'
  });

  // Track a page view immediately (no threshold or observer)
  trackPageView('snap_details_page');

  // Track a custom event programmatically (no DOM element needed)
  trackEvent('chart_tab_switch', { tab: 'architectures', snap: 'firefox' });
</script>

Attributes

| Attribute | Description | |-----------|-------------| | data-analytics-click | Enable click tracking on element | | data-analytics-hover | Enable hover tracking on element | | data-analytics-view | Enable view tracking on element | | data-analytics-view-threshold | Visibility ratio to trigger view (default: 0.75) | | data-analytics-target | Identifier for the element (required) | | data-analytics-* | Custom attributes included in payload |

API

initAnalytics(options)

Initializes all declarative tracking (click, hover, view) and configures the sender.

| Option | Type | Description | |--------|------|-------------| | appName | string | Application identifier (e.g. "snapcraft") | | endpoint | string | URL to send event batches to |

trackPageView(target)

Fires a page_view event immediately. Use this for tracking page visits where you need every visit counted regardless of how quickly the user navigates away.

| Parameter | Type | Description | |-----------|------|-------------| | target | string | Identifier for the page (e.g. "snap_details_page") |

trackEvent(target, attributes?)

Fires a custom event programmatically from JavaScript. Use this when you need to track interactions that can't be captured with HTML data-analytics-* attributes (e.g. dynamic UI changes, JS-driven actions, form submissions).

| Parameter | Type | Description | |-----------|------|-------------| | target | string | Identifier for the event (e.g. "chart_tab_switch") | | attributes | Record<string, string \| number> | Optional key-value pairs sent with the event |

// ES module import
import { trackEvent } from '@canonical/analytics-events';
trackEvent('video_play', { video_id: 'intro', duration: 120 });

// Global (script tag)
window.Analytics.trackEvent('filter_applied', { category: 'games' });

Payload Structure

{
  app_name: "snapcraft",
  events: [
    {
      event_type: "click" | "hover" | "view" | "page_view" | "custom",
      session_id: "session_abc123...",
      target: "signup_btn",
      url: "https://example.com/page",
      attributes: {
        // custom data-analytics-* attributes
        duration_ms: 2500,       // hover and view only
        visibility_ratio: 0.85   // view only
      }
    }
  ]
}

Development

npm install
npm run build    # Build for production
npm run lint     # Check code
npm run lint:fix # Fix lint issues

Test App

A demo page is included in test-app/ to test tracking locally.

npm install
npm run build
npm run dev

Open http://localhost:3000/test-app/ in your browser. Interact with elements and open the Event Log to see captured events.