@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)
• Page view tracking (fires immediately, no 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, trackPageView } 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');
</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")

Payload Structure

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