npm package: @plainapps/analytics-angular
Description: Angular service and module for Plain Web Analytics - privacy-focused, cookie-free analytics
Author: Plain Web Analytics
Latest version: 1.0.2

# @plainapps/analytics-angular

Angular service, module, and directives for [Plain Web Analytics](https://plainwebanalytics.com) - 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

```bash
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)

```typescript
// 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+)

```typescript
// 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

```typescript
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:

```typescript
// 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

```typescript
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.

```typescript
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()`:

```typescript
// 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

```typescript
// 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:

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

## Requirements

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

## Related Packages

- [@plainapps/analytics-core](https://www.npmjs.com/package/@plainapps/analytics-core) - Core analytics library
- [@plainapps/analytics-react](https://www.npmjs.com/package/@plainapps/analytics-react) - React hooks and components
- [@plainapps/analytics-vue](https://www.npmjs.com/package/@plainapps/analytics-vue) - Vue composables and plugin
- [@plainapps/analytics-svelte](https://www.npmjs.com/package/@plainapps/analytics-svelte) - Svelte stores and actions

## License

MIT © [Plain Web Analytics](https://plainwebanalytics.com)