umami-helper

A helper library for Umami tracking that simplifies UTM parameter handling and automatic script loading. This library helps you integrate Umami analytics into your application with built-in UTM tracking persistence and event queuing.

Installation

npm install umami-helper

Usage

1. Initialize UTM Tracking (Optional but Recommended)

The UtmTrackService captures UTM parameters from the URL, persists them to localStorage, and automatically attaches them to future events. This is useful for tracking user acquisition across sessions.

import { UtmTrackService } from 'umami-helper';

const utmService = new UtmTrackService();

// Initialize on app startup (e.g., in your root component or main entry file)
// This will capture UTM params from the current URL and store them.
utmService.init();

// Optionally pass default values
utmService.init({
  utm_source: 'direct',
  utm_medium: 'organic'
});

2. Initialize Umami Service

The UmamiService handles loading the Umami script and sending events.

import { UmamiService } from 'umami-helper';

// Configuration
const config = {
  websiteId: 'YOUR-WEBSITE-ID-FROM-UMAMI', // Required
  scriptUrl: 'https://analytics.umami.is/script.js' // Optional, defaults to this URL
};

// Initialize the service
// You can pass the same utmService instance if you want to share the state
const umamiService = new UmamiService(config, utmService);

3. Track Events

Use the track method to send events to Umami. It automatically attaches any stored UTM parameters to the event data.

// Track a simple event
umamiService.track('signup-button-clicked');

// Track an event with custom properties
umamiService.track('purchase', {
  productId: '123',
  currency: 'USD',
  value: 99.99
});

The service handles:

• Script Loading: Automatically injects the Umami script if not present.
• Queuing: If the script hasn't loaded yet, events are queued and sent once the script is ready.
• UTM Context: Merges stored UTM parameters with your event properties automatically.

API Reference

UtmTrackService

Responsible for managing UTM parameters (source, medium, campaign, term, content) and referrer information.

Methods

• init(defaults?: Record<string, string>): void

  • Captures UTM parameters from window.location.search.
  • Merges them with stored values (localStorage) and any provided defaults.
  • Persists the result to localStorage for future sessions.

• getUtmDetail(): Record<string, string>

  • Returns all stored UTM parameters as a key-value object.

• getUtmDetailInObject(): UtmTrackContext

  • Returns a structured object with typed fields:
    • utm_source
    • utm_medium
    • utm_campaign
    • utm_term
    • utm_content
    • referrer
    • tracked_by

• getUtmDetailByKey(key: string): string | undefined

  • Retrieves a specific UTM value by its key (e.g., 'utm_source').

• clearUtmDetail(): void

  • Clears all stored UTM data from localStorage.

UmamiService

Responsible for interacting with the Umami tracking script.

Constructor

constructor(config: UmamiConfig, utmTrackService?: UtmTrackService)

• config: Configuration object (see below).
• utmTrackService: Optional instance of UtmTrackService. If not provided, a new instance is created internally.

Methods

• track(event: string, props?: any): void
  • Sends an event to Umami.
  • event: Name of the event.
  • props: Optional object with event properties. stored UTM details are automatically merged into this object.

Interfaces

UmamiConfig

interface UmamiConfig {
  /** The specific Website ID generated in your Umami dashboard */
  websiteId: string;
  
  /** 
   * URL to your Umami script. 
   * Default: 'https://analytics.umami.is/script.js' 
   */
  scriptUrl?: string; 
}

UtmTrackContext

interface UtmTrackContext {
  utm_source: string | null;
  utm_medium: string | null;
  utm_campaign: string | null;
  utm_term: string | null;
  utm_content: string | null;
  referrer: string | null;
  tracked_by: 'umami_helper';
}