ngx-umami

Angular library for Umami Analytics - a privacy-focused, lightweight analytics platform.

Features

• 🚀 Easy Setup - Simple standalone configuration with provideUmami()
• 📊 Event Tracking - Track custom events with optional data payloads
• 🔄 Router Integration - Automatic page view tracking on route changes
• 🎯 Directive - Declarative event tracking with umamiTrack directive
• 🔒 Privacy First - Respects Do Not Track, GDPR compliant
• 🌐 SSR Compatible - Works with Angular Universal/SSR
• 📦 Tree-shakeable - Only includes what you use

Compatibility

Installation

# Recommended
pnpm add @cacic-fct/ngx-umami

# Or with npm
npm install @cacic-fct/ngx-umami

# Or with yarn
yarn add @cacic-fct/ngx-umami

Note: We recommend using pnpm for faster installs and better disk space efficiency.

Quick Start

1. Configure in your app

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideUmami, withRouterTracking } from '@cacic-fct/ngx-umami';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideUmami({
      websiteId: 'your-website-id',
      src: 'https://analytics.yourdomain.com/script.js'
    }),
    // Optional: Enable automatic page view tracking on route changes
    withRouterTracking()
  ]
};

2. Track events in components

import { Component } from '@angular/core';
import { injectUmami } from '@cacic-fct/ngx-umami';

@Component({
  selector: 'app-checkout',
  template: `<button (click)="onPurchase()">Buy Now</button>`
})
export class CheckoutComponent {
  private umami = injectUmami();

  onPurchase() {
    this.umami.trackEvent('purchase', {
      product: 'Premium Plan',
      price: 99.99,
      currency: 'USD'
    });
  }
}

3. Or use the directive

import { Component } from '@angular/core';
import { UmamiTrackDirective } from '@cacic-fct/ngx-umami';

@Component({
  selector: 'app-signup',
  standalone: true,
  imports: [UmamiTrackDirective],
  template: `
    <button umamiTrack="signup_click">Sign Up</button>

    <button
      umamiTrack="cta_click"
      [umamiTrackData]="{ location: 'header', variant: 'blue' }">
      Get Started
    </button>
  `
})
export class SignupComponent {}

Configuration Options

provideUmami({
  // Required
  websiteId: 'your-website-id',  // From Umami dashboard
  src: 'https://analytics.example.com/script.js',  // Your Umami script URL

  // Optional
  enabled: true,              // Enable/disable tracking (default: true)
  autoTrack: true,            // Auto track page views (default: true)
  doNotTrack: false,          // Honor browser DNT setting (default: false)
  domains: ['example.com'],   // Restrict to specific domains
  tag: 'production',          // Tag for filtering in dashboard
  excludeSearch: false,       // Exclude URL search params
  excludeHash: false,         // Exclude URL hash
  hostUrl: 'https://proxy.example.com'  // Custom data endpoint
})

API Reference

UmamiService

trackPageView(payload?)

Track a page view manually.

umami.trackPageView();

umami.trackPageView({
  url: '/custom-page',
  title: 'Custom Page Title',
  referrer: 'https://google.com'
});

trackEvent(eventName, eventData?)

Track a custom event.

// Simple event
umami.trackEvent('button_click');

// Event with data (max 50 properties)
umami.trackEvent('form_submit', {
  formName: 'contact',
  fields: 5,
  hasAttachment: true
});

identify(sessionIdOrData, sessionData?)

Identify user sessions.

// With session ID
umami.identify('user-123');

// With session ID and data
umami.identify('user-123', {
  plan: 'premium',
  role: 'admin'
});

// With data only
umami.identify({
  plan: 'premium',
  signupDate: '2024-01-15'
});

isAvailable()

Check if tracking is available.

if (umami.isAvailable()) {
  umami.trackEvent('ready');
}

disable()

Disable tracking programmatically.

umami.disable();

UmamiTrackDirective

Declarative event tracking on DOM elements.

<!-- Track click events -->
<button umamiTrack="signup">Sign Up</button>

<!-- With event data -->
<button
  umamiTrack="download"
  [umamiTrackData]="{ file: 'report.pdf', size: 1024 }">
  Download
</button>

<!-- Track different events -->
<input
  umamiTrack="search_focus"
  umamiTrackOn="focus"
  placeholder="Search...">

<form
  umamiTrack="form_submit"
  umamiTrackOn="submit">
  <!-- form fields -->
</form>

Supported events: click, focus, blur, mouseenter, mouseleave, submit

withRouterTracking()

Enable automatic page view tracking on Angular router navigation.

// app.config.ts
providers: [
  provideRouter(routes),
  provideUmami({
    websiteId: 'xxx',
    src: 'https://...',
    autoTrack: false  // Disable Umami's auto-track since router handles it
  }),
  withRouterTracking()
]

provideUmamiWithFactory()

Configure Umami using a factory function with dependency injection.

import { provideUmamiWithFactory } from '@cacic-fct/ngx-umami';
import { ConfigService } from './config.service';

providers: [
  provideUmamiWithFactory(
    (config: ConfigService) => ({
      websiteId: config.umamiWebsiteId,
      src: config.umamiSrc,
      enabled: config.isProduction
    }),
    [ConfigService]
  )
]

Environment-based Configuration

// environments/environment.ts
export const environment = {
  production: false,
  umami: {
    websiteId: 'dev-website-id',
    src: 'https://analytics.example.com/script.js',
    enabled: false  // Disable in development
  }
};

// environments/environment.prod.ts
export const environment = {
  production: true,
  umami: {
    websiteId: 'prod-website-id',
    src: 'https://analytics.example.com/script.js',
    enabled: true
  }
};

// app.config.ts
import { environment } from './environments/environment';

providers: [
  provideUmami(environment.umami)
]

SSR Considerations

The library automatically handles server-side rendering. Tracking is only active in the browser environment - no configuration needed.

License

MIT