@entrolytics/angular-sdk

Angular SDK for Entrolytics - First-party growth analytics for the edge.

Features

• 🚀 Angular 16+ Support - Full compatibility with modern Angular versions
• 🔄 RxJS Integration - Observable-based API for reactive tracking
• 🎯 Component Tracking - Automatic component interaction tracking
• 🛣️ Route Change Detection - Automatic page view tracking
• 🔧 Angular DI - Proper dependency injection setup
• 📊 Debug Mode - Built-in debugging capabilities

Installation

npm install @entrolytics/angular-sdk
# or
yarn add @entrolytics/angular-sdk

Quick Start

1. Import the Module

import { EntrolyticsModule } from '@entrolytics/angular-sdk'

@NgModule({
  imports: [
    // ... other imports
    EntrolyticsModule.forRoot({
      endpoint: 'https://entrolytics.click',
      apiKey: 'your-api-key',
      websiteId: 'your-website-id',
      debug: true // optional
    })
  ],
})
export class AppModule { }

2. Use the Service

import { Component } from '@angular/core'
import { EntrolyticsService } from '@entrolytics/angular-sdk'

@Component({
  selector: 'app-my-component',
  template: `
    <button (click)="trackClick()">Track Click</button>
  `
})
export class MyComponent {
  constructor(private entrolytics: EntrolyticsService) {}

  trackClick() {
    this.entrolytics.trackComponent('MyComponent', 'button-click', {
      buttonText: 'Track Click'
    })
  }
}

API Reference

EntrolyticsService

initialize(config: EntrolyticsConfig)

Initialize the SDK with your configuration.

this.entrolytics.initialize({
  endpoint: 'https://entrolytics.click',
  apiKey: 'your-api-key',
  websiteId: 'your-website-id',
  debug: true
})

track(event: Event)

Track a custom event.

this.entrolytics.track({
  event: 'custom_event',
  properties: {
    button: 'submit',
    form: 'contact'
  }
})

identify(userId: string, traits?: Record<string, any>)

Identify a user.

this.entrolytics.identify('user123', {
  email: '[email protected]',
  name: 'John Doe'
})

page(name?: string, properties?: Record<string, any>)

Track a page view.

this.entrolytics.page('Dashboard', {
  user_type: 'premium'
})

Angular-Specific Methods

trackComponent(component: string, action: string, properties?: Record<string, any>)

Track component interactions.

this.entrolytics.trackComponent('UserProfile', 'edit_click', {
  field: 'email'
})

trackDirective(directive: string, properties?: Record<string, any>)

Track directive interactions.

this.entrolytics.trackDirective('clickOutside', {
  element: 'dropdown'
})

trackRouteChange(route: string, properties?: Record<string, any>)

Track route changes.

this.entrolytics.trackRouteChange('/users/123', {
  user_id: '123'
})

Advanced Usage

Manual Initialization

If you prefer manual initialization:

export class AppComponent implements OnInit {
  constructor(private entrolytics: EntrolyticsService) {}

  ngOnInit() {
    this.entrolytics.initialize({
      endpoint: 'https://entrolytics.click',
      apiKey: 'your-api-key',
      websiteId: 'your-website-id'
    })
  }
}

Router Integration

For automatic route tracking:

import { Router, NavigationEnd } from '@angular/router'
import { filter } from 'rxjs/operators'

export class AppComponent implements OnInit {
  constructor(
    private router: Router,
    private entrolytics: EntrolyticsService
  ) {}

  ngOnInit() {
    this.router.events
      .pipe(filter(event => event instanceof NavigationEnd))
      .subscribe((event: NavigationEnd) => {
        this.entrolytics.trackRouteChange(event.urlAfterRedirects)
      })
  }
}

HTTP Interceptor

Track all HTTP requests:

import { Injectable } from '@angular/core'
import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent } from '@angular/common/http'
import { Observable } from 'rxjs'
import { tap } from 'rxjs/operators'
import { EntrolyticsService } from '@entrolytics/angular-sdk'

@Injectable()
export class AnalyticsInterceptor implements HttpInterceptor {
  constructor(private entrolytics: EntrolyticsService) {}

  intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
    const startTime = Date.now()
    
    return next.handle(req).pipe(
      tap({
        next: () => {
          const duration = Date.now() - startTime
          this.entrolytics.track({
            event: 'http_request',
            properties: {
              method: req.method,
              url: req.url,
              duration
            }
          })
        }
      })
    )
  }
}

Configuration

EntrolyticsConfig

| Option | Type | Required | Description | |--------|------|----------|-------------| | endpoint | string | Yes | Your Entrolytics endpoint | | apiKey | string | Yes | Your API key | | websiteId | string | Yes | Your website ID | | debug | boolean | No | Enable debug logging (default: false) |

Error Handling

The SDK includes built-in error handling:

this.entrolytics.track({
  event: 'purchase',
  properties: { amount: 99.99 }
}).subscribe({
  next: () => console.log('Event tracked successfully'),
  error: (err) => console.error('Tracking failed:', err)
})

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

Contributions are welcome! Please read our contributing guidelines.

License

MIT