Package Exports

@plainapps/analytics-angular

Readme

@plainapps/analytics-angular

Angular service, module, and directives for Plain Web Analytics - privacy-focused, cookie-free web analytics.

Features

🔒 Privacy-first - No cookies, no personal data collection
🎯 Angular-native - Service, module, and directives
📦 Lightweight - Minimal bundle size impact
🔄 Auto route tracking - Automatic pageview tracking with Angular Router
✨ Declarative directives - Track events and goals declaratively
📱 SSR compatible - Works with Angular Universal
🎨 Standalone components - Full support for Angular 14+ standalone API

Installation

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

Quick Start

Using NgModule (Traditional)

// app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule } from '@angular/router';
import { PlainAnalyticsModule } from '@plainapps/analytics-angular';

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

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    RouterModule.forRoot([/* your routes */]),
    PlainAnalyticsModule.forRoot({
      siteId: 'pwa_site_abc123', // Your site key from dashboard
      autoPageview: true,        // Track initial pageview
      trackRouteChanges: true,   // Track Angular route changes
      debug: false               // Enable console logging in dev
    })
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

Using Standalone API (Angular 14+)

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideRouter } from '@angular/router';
import { providePlainAnalytics } from '@plainapps/analytics-angular';

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

bootstrapApplication(AppComponent, {
  providers: [
    provideRouter(routes),
    providePlainAnalytics({
      siteId: 'pwa_site_abc123',
      autoPageview: true,
      trackRouteChanges: true
    })
  ]
});

Usage

Using the Service

import { Component } from '@angular/core';
import { PlainAnalyticsService } from '@plainapps/analytics-angular';

@Component({
  selector: 'app-signup',
  template: `
    <form (ngSubmit)="onSubmit()">
      <input [(ngModel)]="email" name="email" placeholder="Email" />
      <button type="submit">Sign Up</button>
    </form>
  `
})
export class SignupComponent {
  email = '';

  constructor(private analytics: PlainAnalyticsService) {}

  onSubmit() {
    // Track custom event
    this.analytics.trackEvent('signup_attempt', {
      source: 'landing_page'
    });

    // After successful signup
    this.analytics.trackGoal('signup', {
      revenue: 0,
      properties: { plan: 'free' }
    });
  }
}

Using Directives

Import the directives in your component or module:

// With standalone components
import { Component } from '@angular/core';
import { TrackEventDirective, TrackGoalDirective } from '@plainapps/analytics-angular';

@Component({
  selector: 'app-pricing',
  standalone: true,
  imports: [TrackEventDirective, TrackGoalDirective],
  template: `
    <!-- Track click events -->
    <button paTrackEvent="view_pricing">View Pricing</button>
    
    <!-- Track with properties -->
    <button 
      paTrackEvent="select_plan" 
      [paEventProperties]="{ plan: 'pro', price: 1000 }">
      Select Pro Plan
    </button>
    
    <!-- Track goals -->
    <button paTrackGoal="purchase" [paGoalRevenue]="9900">
      Buy Now ($99)
    </button>
    
    <!-- Track on custom events -->
    <input 
      paTrackEvent="search_focus" 
      paEventOn="focus"
      placeholder="Search..." />
  `
})
export class PricingComponent {}

Track Element Visibility

import { Component } from '@angular/core';
import { TrackVisibleDirective } from '@plainapps/analytics-angular';

@Component({
  selector: 'app-landing',
  standalone: true,
  imports: [TrackVisibleDirective],
  template: `
    <!-- Track when section becomes visible -->
    <section 
      paTrackVisible="pricing_section_viewed"
      [paVisibleProperties]="{ page: 'landing' }">
      <h2>Pricing</h2>
      <!-- ... -->
    </section>

    <!-- Track with custom threshold -->
    <div 
      paTrackVisible="cta_visible"
      [paVisibleThreshold]="0.75"
      [paVisibleOnce]="true">
      Call to Action
    </div>
  `
})
export class LandingComponent {}

API Reference

PlainAnalyticsModule

`forRoot(config)`

Configure analytics for the root module.

PlainAnalyticsModule.forRoot({
  siteId: string;           // Required: Your site key
  apiEndpoint?: string;     // Custom API endpoint
  autoPageview?: boolean;   // Track initial pageview (default: true)
  hashMode?: boolean;       // Track hash changes (default: false)
  debug?: boolean;          // Enable debug logging (default: false)
  trackRouteChanges?: boolean; // Auto-track route changes (default: true)
})

`forChild()`

Import in lazy-loaded modules (uses root config).

providePlainAnalytics(config)

Standalone provider function with same config options as forRoot().

PlainAnalyticsService

Method	Description
`init(config)`	Manual initialization (if not using module config)
`trackPageview(url?)`	Track a pageview
`trackEvent(name, properties?)`	Track a custom event
`trackGoal(goalId, options?)`	Track a goal conversion
`setEnabled(enabled)`	Enable/disable tracking
`isInitialized()`	Check if initialized
`isEnabled()`	Check if tracking is enabled
`getConfig()`	Get current configuration

Directives

TrackEventDirective

Input	Type	Default	Description
`paTrackEvent`	string	-	Event name (required)
`paEventProperties`	object	-	Custom properties
`paEventOn`	string	'click'	DOM event to listen for

TrackGoalDirective

Input	Type	Default	Description
`paTrackGoal`	string	-	Goal ID (required)
`paGoalRevenue`	number	-	Revenue in cents
`paGoalProperties`	object	-	Custom properties
`paGoalOn`	string	'click'	DOM event to listen for

TrackVisibleDirective

Input	Type	Default	Description
`paTrackVisible`	string	-	Event name (required)
`paVisibleProperties`	object	-	Custom properties
`paVisibleOnce`	boolean	true	Track only once
`paVisibleThreshold`	number	0.5	Visibility threshold (0-1)

Lazy Loading

For lazy-loaded feature modules, use forChild():

// feature.module.ts
import { NgModule } from '@angular/core';
import { PlainAnalyticsModule } from '@plainapps/analytics-angular';

@NgModule({
  imports: [
    PlainAnalyticsModule.forChild()
  ]
})
export class FeatureModule {}

Angular Universal (SSR)

The library automatically detects server-side rendering and disables tracking during SSR. No additional configuration needed.

Opt-out Support

// Let users opt out of tracking
this.analytics.setEnabled(false);

// Check status
if (this.analytics.isEnabled()) {
  // Tracking is active
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  PlainAnalyticsModuleConfig,
  AnalyticsConfig,
  EventProperties
} from '@plainapps/analytics-angular';

Requirements

Angular 12 or higher
@plainapps/analytics-core (peer dependency)
rxjs 6.0 or higher

@plainapps/analytics-core - Core analytics library
@plainapps/analytics-react - React hooks and components
@plainapps/analytics-vue - Vue composables and plugin
@plainapps/analytics-svelte - Svelte stores and actions

JSPM