@canonical/analytics-events

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)
• 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 } from '@canonical/analytics-events';
  initAnalytics({
    appName: 'snapcraft',
    endpoint: 'https://marketplace-analytics.canonical.com/analytics/events'
  });
</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

Payload Structure

{
  app_name: "snapcraft",
  events: [
    {
      event_type: "click" | "hover" | "view",
      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.