<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';

  // Send to GA4 via the site's existing Google Tag Manager
  initAnalytics({
    appName: 'snapcraft',
    gtm: true
  });

  // ...or send to an HTTP backend instead
  // initAnalytics({
  //   appName: 'snapcraft',
  //   endpoint: 'https://marketplace-analytics.canonical.com/analytics/events'
  // });

  // Track a page view immediately (HTTP destination; ignored for GA4/GTM)
  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 destination.

Option	Type	Description
`appName`	`string`	Application identifier (e.g. `"snapcraft"`)
`endpoint`	`string`	URL to POST event batches to (HTTP backend)
`gtm`	`boolean`	Send to GA4 via an existing GTM container

Provide one destination. Precedence is gtm -> endpoint; if none is set, declarative tracking is not initialized and events are not delivered.

Destinations

The package can deliver events to different destinations:

HTTP backend (endpoint) — batches events (10 events or 10s) and POSTs them via navigator.sendBeacon / fetch. The payload is the structure below.
Google Analytics 4 via GTM (gtm: true) — pushes each event onto the page's existing dataLayer as { event: "analytics_event", ga_event_name, ...params }. The site's Google Tag Manager container then forwards them to GA4. Configure GTM with a trigger on the analytics_event custom event and a GA4 event tag whose event name is the ga_event_name data-layer variable. This reuses the site's existing GTM/GA setup — no second Google loader.

How events map to GA4

Event type	GA4 event name	Notes
`page_view`	—	Not sent; GA4 collects page views automatically
`custom`	the `target` value	e.g. `chart_tab_switch`
`click`	`ui_click`	`target` is sent as a parameter
`view`	`ui_view`	`target` is sent as a parameter
`hover`	`ui_hover`	`target` is sent as a parameter

Page views use GA4's automatic page-view tracking (enhanced measurement) — the package does not send its own, and the GA4/GTM destination ignores page_view events (including those from trackPageView). Declarative types are prefixed (ui_click, etc.) to avoid clashing with GA4's built-in event names. Event and parameter names are truncated to GA4's limits (names <= 40 chars, string values <= 100 chars).

Parameters

All event attributes are forwarded to GA4 as event parameters (alongside event_type and app_name). Only the package's internal fields — session_id and url — are not sent (GA4 has its own session model and captures page_location automatically).

The package is intentionally generic: it does not filter application-specific fields. If a consuming app collects high-cardinality or sensitive attributes (e.g. free-text queries, per-request IDs) that should not go to GA4, it is responsible for not attaching them on the GA4 destination.

`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

This is the batch payload sent to the HTTP endpoint destination. (For GA4, see How events map to GA4 above.)

{
  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.

Keywords

analytics events tracking