Analytics Tracker

A comprehensive Angular analytics tracking library for frontend applications. This package provides easy-to-use services and directives for tracking user interactions, page views, and custom events across your Angular applications.

Features

• 🎯 Easy Integration: Simple module-based setup with configuration
• 📊 Comprehensive Tracking: Track page views, clicks, and custom events
• 🔧 Flexible Configuration: Customizable API endpoints and authentication
• 📱 Session Management: Automatic session and unique tab ID generation
• 🎨 Directive Support: Built-in directive for easy click tracking
• 🚀 TypeScript Support: Full TypeScript support with type definitions
• 📦 Angular 17+ Compatible: Built for modern Angular applications (17.x, 18.x, 19.x)

Installation

npm install analytics-tracker

Quick Start

1. Import the Module

In your app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AnalyticsTrackerModule } from 'analytics-tracker';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    AnalyticsTrackerModule.forRoot({
      apiKey: 'your-api-key',
      apiUrl: 'https://your-analytics-api.com/events'
    })
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

2. Track Page Views

In your components:

import { Component } from '@angular/core';
import { AnalyticsTrackerService } from 'analytics-tracker';

@Component({
  selector: 'app-home',
  template: '<h1>Welcome to Home Page</h1>'
})
export class HomeComponent {
  constructor(private analytics: AnalyticsTrackerService) {
    // Track page view
    this.analytics.trackPageview('HomePage', 'Main');
  }
}

3. Track User Interactions

Using the Service

import { Component } from '@angular/core';
import { AnalyticsTrackerService } from 'analytics-tracker';

@Component({
  selector: 'app-button',
  template: `
    <button (click)="onButtonClick()">
      Click Me
    </button>
  `
})
export class ButtonComponent {
  constructor(private analytics: AnalyticsTrackerService) {}

  onButtonClick() {
    this.analytics.trackFeatureClick(
      'ButtonClick',
      'HomePage',
      'Main',
      { buttonId: 'cta-button', value: 'clicked' }
    );
  }
}

Using the Directive

import { Component } from '@angular/core';

@Component({
  selector: 'app-feature',
  template: `
    <button 
      trackClick="FeatureButtonClick"
      screenName="HomePage"
      moduleName="Main"
      [trackData]="{ feature: 'premium-upgrade' }">
      Upgrade to Premium
    </button>
  `
})
export class FeatureComponent {}

API Reference

AnalyticsTrackerService

Methods

trackPageview(screenName: string, moduleName?: string)

Tracks a page view event.

Parameters:

• screenName (string): Name of the screen/page being viewed
• moduleName (string, optional): Module name (defaults to 'Navigation')

trackFeatureClick(actionName: string, screenName: string, moduleName: string, extraData?: object)

Tracks a user interaction event.

Parameters:

• actionName (string): Name of the action performed
• screenName (string): Name of the screen where action occurred
• moduleName (string): Module name
• extraData (object, optional): Additional data to track

getCurrentTabId(): string

Gets the current tab ID for debugging purposes.

Returns: The unique tab ID for this tab

getCurrentSessionId(): string

Gets the current session ID for debugging purposes.

Returns: The session ID

trackEvent(eventName: string, extraData?: object): void

Tracks a simple custom event with just the event name.

Parameters:

• eventName (string): Name of the event to track
• extraData (object, optional): Additional data to include in the event

trackCustomEvent(eventName: string, screenName: string, moduleName: string, extraData?: object): void

Tracks a custom event with full control over the payload.

Parameters:

• eventName (string): Name of the event to track
• screenName (string): Screen where the event occurred
• moduleName (string): Module name
• extraData (object, optional): Additional data to include in the event

TrackClickDirective

A standalone directive for easy click tracking.

Inputs

• trackClick (string): Action name to track
• screenName (string): Screen name where click occurred
• moduleName (string): Module name
• trackData (object, optional): Additional data to track

AnalyticsConfig

Configuration interface for the analytics module.

interface AnalyticsConfig {
  apiKey: string;    // Your API key for authentication
  apiUrl: string;    // Your analytics API endpoint
}

Event Payload Structure

All events are automatically enriched with the following data:

{
  module: string,           // Module name
  action: string,           // Action performed
  screen: string,           // Screen name
  type: string,             // Event type ('Navigation' or 'UserInteraction')
  sessionId: string,        // Unique session identifier
  tabId: string,            // Unique tab identifier
  userId: string,           // User identifier (from sessionStorage)
  eventTimestamp: string,   // ISO timestamp
  dataSource: 'FRONTEND',   // Always 'FRONTEND'
  ...extraData              // Any additional data provided
}

User ID Management

The library automatically reads the user ID from sessionStorage using the key analytics_user_id. Set this value in your application's login logic:

// In your login service
sessionStorage.setItem('analytics_user_id', user.id);

Session Management

• Session ID: Automatically generated and stored in sessionStorage as analytics_session_id
• Tab ID: Automatically generated unique ID for each tab using multiple uniqueness sources:
  • Timestamp (Date.now())
  • Random string (Math.random())
  • Performance timing (performance.now())
  • Micro-timestamp for additional uniqueness
• Persistence:
  • Session ID persists across page reloads but not across browser sessions
  • Tab ID persists across page reloads within the same tab
  • Each new tab gets a completely unique tab ID

Development

Building the Library

# Build the library
npm run build:lib

# Build for production
npm run build:lib:prod

# Build and watch for changes
npm run build:lib:watch

Testing

# Run unit tests
npm test

Publishing

# Build the library
npm run build:lib:prod

# Pack the library (creates .tgz file)
npm run pack:lib

# Publish to npm
npm run publish:lib

Requirements

• Angular 17.0.0 or higher
• TypeScript 5.7.2 or higher
• Node.js 18 or higher

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.