Angular Integration

The @kitbase/analytics-angular package wraps the core SDK with Angular-native dependency injection via provideKitbaseAnalytics() and an injectable KitbaseAnalyticsService.

Standalone-First

The package uses provideKitbaseAnalytics() which works with standalone Angular applications (Angular 14+). No NgModule is required.

Installation

npm

npm install @kitbase/analytics-angular

pnpm

pnpm add @kitbase/analytics-angular

yarn

yarn add @kitbase/analytics-angular

Setup

Register the provider in your application config. The SDK initializes eagerly at bootstrap so auto-tracking is active immediately.

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

export const appConfig: ApplicationConfig = {
  providers: [
    provideKitbaseAnalytics({
      sdkKey: 'YOUR_SDK_KEY',
    }),
  ],
};

INFO

SDK keys are public and safe to commit to source control. They are used only to identify which project to send traffic to and do not grant access to your data.

Configuration Options

All options beyond sdkKey are optional. Sensible defaults are applied automatically.

provideKitbaseAnalytics({
  sdkKey: 'YOUR_SDK_KEY',
  debug: false,

  analytics: {
    autoTrackPageViews: true,       // Tracks pushState / popstate navigations
    autoTrackClicks: true,          // Tracks clicks on interactive elements
    autoTrackOutboundLinks: true,   // Tracks clicks on external links
    autoTrackScrollDepth: true,     // Tracks max scroll depth per page
    autoTrackVisibility: true,      // Tracks element visibility via data attributes
    autoTrackWebVitals: false,      // Requires 'web-vitals' package
    autoDetectFrustration: true,    // Detects rage clicks and dead clicks
  },

  offline: {
    enabled: false,
    maxQueueSize: 1000,
    flushInterval: 30000,           // 30 seconds
    flushBatchSize: 50,
    maxRetries: 3,
  },

  botDetection: {
    enabled: true,
  },
});

Auto-Tracking

Everything below is enabled by default — no manual wiring needed. The SDK patches history.pushState and listens for popstate, so Angular Router navigations are captured automatically.

Feature	Config Key	What It Tracks
Page views	autoTrackPageViews	Initial load + SPA navigations (pushState / popstate)
Clicks	autoTrackClicks	Clicks on buttons, links, inputs, and other interactive elements
Outbound links	autoTrackOutboundLinks	Clicks on links to external domains
Scroll depth	autoTrackScrollDepth	Maximum scroll percentage per page
Element visibility	autoTrackVisibility	Time an element is visible in the viewport (via data attributes)
Frustration signals	autoDetectFrustration	Rage clicks (3+ rapid clicks) and dead clicks (no DOM change)
Web Vitals	autoTrackWebVitals	LCP, CLS, INP, FCP, TTFB (requires web-vitals package)

Data Attributes

Use data attributes for declarative tracking without writing TypeScript.

Click tracking — fires a custom event when the element is clicked:

<button data-kb-track-click="CTA Clicked"
        data-kb-click-channel="marketing">
  Sign Up
</button>

Visibility tracking — measures how long an element is visible in the viewport:

<div data-kb-track-visibility="Pricing Section Viewed"
     data-kb-visibility-channel="marketing"
     data-kb-visibility-threshold="0.75">
  Pricing details...
</div>

Attribute	Description
data-kb-track-click	Event name fired on click
data-kb-click-channel	Channel for the click event (default: 'engagement')
data-kb-track-visibility	Event name fired when element leaves viewport
data-kb-visibility-channel	Channel for the visibility event (default: 'engagement')
data-kb-visibility-threshold	IntersectionObserver threshold 0–1 (default: 0.5)

Using the Service

Inject KitbaseAnalyticsService into any component or service.

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

@Component({ selector: 'app-checkout', templateUrl: './checkout.component.html' })
export class CheckoutComponent {
  private kitbase = inject(KitbaseAnalyticsService);

  async onPurchase(order: Order): Promise<void> {
    await this.kitbase.track({
      channel: 'payments',
      event: 'Purchase Completed',
      tags: { amount: order.total, items: order.items.length },
    });

    await this.kitbase.trackRevenue({
      amount: order.total,
      currency: order.currency,
    });
  }
}

API Reference

Event Tracking

// Custom event
kitbase.track({ channel: 'ui', event: 'Button Clicked', tags: { location: 'header' } });

// Page view (usually automatic — call manually only if needed)
kitbase.trackPageView({ path: '/custom-path' });

// Revenue
kitbase.trackRevenue({ amount: 1999, currency: 'USD', tags: { plan: 'premium' } });

// Outbound link
kitbase.trackOutboundLink({ url: 'https://example.com', text: 'Visit Example' });

User Identity

// Identify after login
await kitbase.identify({
  userId: 'user_123',
  traits: { email: 'user@example.com', plan: 'premium' },
});

// Get current user ID
const id = kitbase.getUserId(); // string | null

// Clear identity on logout
kitbase.reset();

See Identify Users for more on how identity resolution works.

Super Properties

Attach properties to every subsequent event automatically.

// Merge properties into all future events
kitbase.register({ app_version: '2.4.1', platform: 'web' });

// Set only if not already registered
kitbase.registerOnce({ initial_referrer: document.referrer });

// Remove a single property
kitbase.unregister('platform');

// Read or clear all
kitbase.getSuperProperties();
kitbase.clearSuperProperties();

Time Events

Measure duration between two points.

// Start a timer
kitbase.timeEvent('Checkout Flow');

// ... user completes checkout ...

// The next track() call for this event name automatically includes the duration
await kitbase.track({ channel: 'conversions', event: 'Checkout Flow' });

// Other helpers
kitbase.getTimedEvents();                 // string[]
kitbase.getEventDuration('Checkout Flow'); // number | null (ms)
kitbase.cancelTimeEvent('Checkout Flow');  // stop without tracking

Plugins

kitbase.use(myPlugin);        // Register a plugin
kitbase.getPlugins();         // string[] — active plugin names

Utilities

kitbase.setDebugMode(true);   // Enable console logging
kitbase.isDebugMode();        // boolean
kitbase.shutdown();           // Cleanup and stop all tracking
kitbase.getInstance();        // Access the underlying core SDK instance

Next Steps

• Autocapture — Full reference of automatically tracked events
• Custom Events — Channels, tags, and notifications
• Identify Users — Identity resolution and user properties
• JavaScript SDK — Full SDK reference including offline support