@kitbase/analytics-angular

Angular integration for the Kitbase Analytics SDK.

Installation

npm install @kitbase/analytics-angular
# or
pnpm add @kitbase/analytics-angular
# or
yarn add @kitbase/analytics-angular

Usage

Option 1: Direct — just call init()

No Angular DI needed. Call init() anywhere (e.g. main.ts, a component, a service):

import { init } from '@kitbase/analytics-angular';

const kitbase = init({ sdkKey: 'your-api-key' });

// Track events
kitbase.track({ channel: 'ui', event: 'Button Clicked' });

// Identify users
kitbase.identify({ userId: 'user-123', traits: { email: '[email protected]' } });

You can retrieve the instance later with getInstance():

import { getInstance } from '@kitbase/analytics-angular';

const kitbase = getInstance();
kitbase?.track({ channel: 'ui', event: 'Page Loaded' });

Option 2: Angular DI — provideKitbaseAnalytics() + inject()

Register the provider in your app config, then inject it in any component or service:

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKitbaseAnalytics({
      sdkKey: 'your-sdk-key',
      debug: true,
    }),
  ],
};

// component.ts
import { Component, inject } from '@angular/core';
import { KitbaseAnalyticsService } from '@kitbase/analytics-angular';

@Component({
  selector: 'app-button',
  template: '<button (click)="onClick()">Click me</button>',
})
export class ButtonComponent {
  private kitbase = inject(KitbaseAnalyticsService);

  onClick() {
    this.kitbase.track({
      channel: 'ui',
      event: 'Button Clicked',
      tags: { button_id: 'cta' },
    });
  }
}

Configuration

init({
  // Required
  sdkKey: 'your-api-key',

  // Optional
  debug: true,
  baseUrl: 'https://api.kitbase.dev',

  analytics: {
    autoTrackPageViews: true,     // track route changes automatically
    autoTrackOutboundLinks: true, // track external link clicks
    autoTrackClicks: true,        // track button/link/input clicks + data-kb-track-click
    autoTrackScrollDepth: true,   // track max scroll depth per page
    autoTrackVisibility: true,    // track visibility duration via data attributes
    autoTrackWebVitals: false,    // track Core Web Vitals (LCP, CLS, INP, FCP, TTFB)
    autoDetectFrustration: true,  // detect rage clicks and dead clicks
  },

  offline: {
    enabled: true,                // queue events when offline
    maxQueueSize: 1000,
    flushInterval: 30000,
    flushBatchSize: 50,
    maxRetries: 3,
  },
});

Page views, clicks, outbound links, scroll depth, and visibility duration are tracked automatically by default. The core SDK intercepts history.pushState/popstate, so no Angular Router integration is needed.

Data Attribute Events

Track events from HTML using data attributes — no JavaScript needed. Works in Angular, React, or vanilla HTML.

Click Tracking

Fire a named event when a user clicks an element:

<!-- Basic -->
<button data-kb-track-click="CTA Clicked">Sign Up Now</button>

<!-- With custom channel -->
<button data-kb-track-click="Add to Cart" data-kb-click-channel="ecommerce">
  Add to Cart
</button>

| Attribute | Required | Default | Description | |-----------|----------|---------|-------------| | data-kb-track-click | Yes | — | Event name to fire | | data-kb-click-channel | No | 'engagement' | Channel for the event |

Elements with data-kb-track-click skip the generic auto-click tracking to avoid double-counting. Disable with autoTrackClicks: false.

Visibility Duration

Track how long elements are visible in the viewport:

<!-- Basic -->
<section data-kb-track-visibility="Pricing Section Viewed">...</section>

<!-- With optional channel and threshold -->
<div
  data-kb-track-visibility="Hero Banner Viewed"
  data-kb-visibility-channel="marketing"
  data-kb-visibility-threshold="0.5"
>...</div>

| Attribute | Required | Default | Description | |-----------|----------|---------|-------------| | data-kb-track-visibility | Yes | — | Event name to fire | | data-kb-visibility-channel | No | 'engagement' | Channel for the event | | data-kb-visibility-threshold | No | 0.5 | IntersectionObserver threshold (0–1) |

When the element leaves the viewport, navigates away, or is removed from the DOM, the SDK fires an event with duration_seconds and duration_ms tags.

Dynamically added elements (e.g. from Angular @if or *ngIf) are picked up automatically via MutationObserver. Disable with autoTrackVisibility: false.

Web Vitals

Track Core Web Vitals by enabling autoTrackWebVitals:

init({
  sdkKey: 'your-api-key',
  analytics: {
    autoTrackWebVitals: true,
  },
});

The SDK collects all 5 metrics (LCP, CLS, INP, FCP, TTFB) and sends them as a single web_vitals event. Metrics are sent once per page load with a 30-second timeout. Only collected metrics are included. See the core SDK README for full details.

API Reference

Event Tracking

| Method | Description | |--------|-------------| | track(options) | Track a custom event | | trackPageView(options?) | Track a page view | | trackRevenue(options) | Track a revenue event | | trackOutboundLink(options) | Track an outbound link click | | trackClick(tags) | Track a click event |

User Identification

| Method | Description | |--------|-------------| | identify(options) | Identify a user with traits | | getUserId() | Get the identified user ID | | reset() | Reset user identity |

Super Properties

| Method | Description | |--------|-------------| | register(properties) | Set super properties (included in all events) | | registerOnce(properties) | Set super properties only if not already set | | unregister(key) | Remove a super property | | getSuperProperties() | Get all super properties | | clearSuperProperties() | Clear all super properties |

Time Events

| Method | Description | |--------|-------------| | timeEvent(eventName) | Start timing an event | | cancelTimeEvent(eventName) | Cancel timing an event | | getTimedEvents() | List all active timed events | | getEventDuration(eventName) | Get elapsed time in ms |

Plugin System

| Method | Description | |--------|-------------| | use(plugin) | Register a plugin | | getPlugins() | Get names of all registered plugins |

Debug

| Method | Description | |--------|-------------| | setDebugMode(enabled) | Toggle debug logging | | isDebugMode() | Check if debug mode is on | | shutdown() | Shutdown the SDK and cleanup | | getInstance() | Get the underlying KitbaseAnalytics instance |

Examples

Track Events

kitbase.track({
  channel: 'ecommerce',
  event: 'Add to Cart',
  tags: { product_id: 'sku-123', price: 29.99 },
});

Identify Users

await kitbase.identify({
  userId: user.id,
  traits: { email: user.email, plan: user.plan },
});

// On logout
kitbase.reset();

Track Duration

// Start timer
kitbase.timeEvent('Video Watched');

// ... user watches video ...

// Track event — $duration tag is automatically included
kitbase.track({
  channel: 'engagement',
  event: 'Video Watched',
  tags: { video_id: 'abc' },
});

Track Revenue

kitbase.trackRevenue({
  amount: 19.99,
  currency: 'USD',
  tags: { plan: 'pro', cycle: 'monthly' },
});

Plugins

import { KitbaseAnalyticsService, WebVitalsPlugin } from '@kitbase/analytics-angular';

@Component({
  selector: 'app-root',
  template: '<router-outlet />',
})
export class AppComponent {
  private kitbase = inject(KitbaseAnalyticsService);

  constructor() {
    this.kitbase.use(new WebVitalsPlugin());
    console.log('Active plugins:', this.kitbase.getPlugins());
  }
}

Re-exported Types

All types, errors, and utilities from @kitbase/analytics are re-exported:

import {
  type KitbaseConfig,
  type TrackOptions,
  type KitbasePlugin,
  KitbaseError,
  ValidationError,
} from '@kitbase/analytics-angular';

Running the Example App

cd examples
pnpm install
pnpm start

Opens at http://localhost:4200 with an interactive dashboard to test all SDK features.

License

MIT