Usage Guide

This guide covers the primary ways to track user activity with Angulartics2: automatic page tracking, declarative event tracking in templates, and programmatic event tracking in your code.

Automatic Page View Tracking

Once you have completed the Installation and called startTracking() in your root component, Angulartics2 will automatically listen for route changes from the Angular Router and send a pageTrack event.

This means you get page view tracking out-of-the-box without any additional code for each route.

To customize this behavior (e.g., exclude routes or clean up URLs), see the Configuration guide.

Event Tracking

Beyond page views, you'll often want to track specific user interactions like button clicks, form submissions, or video plays. Angulartics2 offers two ways to do this.

1. Declarative Tracking in Templates (HTML)

The easiest way to track events is by using the angulartics2On directive directly in your component templates.

<div 
  angulartics2On="click" 
  angularticsAction="DownloadClick" 
  angularticsLabel="song-title.mp3" 
  angularticsValue="10" 
  [angularticsCategory]="'Music'"
  [angularticsProperties]="{ 'fileType': 'MP3', 'campaign': 'Fall Campaign' }">
  Download Now
</div>

Directive Inputs

• angulartics2On: The name of the DOM event to track (e.g., click, mouseover, submit).
• angularticsAction: (Required) The name of the event you are tracking (e.g., DownloadClick, SignUp).
• angularticsCategory: The category of the event (e.g., Music, User Auth).
• angularticsLabel: An optional label for additional context.
• angularticsValue: An optional numeric value associated with the event.
• angularticsProperties: An object containing any additional custom properties you want to send with the event.

2. Programmatic Tracking in Code (TypeScript)

For more complex scenarios, you can inject the Angulartics2 service into your components and track events programmatically.

This is useful when:

• The event is not a standard DOM event (e.g., after a successful HTTP request).
• The properties you need to track are only available within your component's logic.

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

@Component({
  selector: 'app-some-component',
  template: '<button (click)="onDownload()">Download</button>'
})
export class SomeComponent {

  constructor(private angulartics2: Angulartics2) {}

  onDownload() {
    // Business logic for downloading a file...

    // Track the event programmatically
    this.angulartics2.eventTrack.next({ 
      action: 'DownloadSuccess',
      properties: { 
        category: 'Downloads',
        label: 'data-report.csv',
        fileSize: 1024, // custom property
      },
    });
  }
}

Tracking User Information

Most analytics providers support identifying users and attaching properties to their profiles. Angulartics2 provides a unified API for this.

Identifying Users (setUsername)

When a user logs in or their identity becomes known, you can associate all future tracking with that user ID.

import { Angulartics2 } from 'angulartics2';

// ... inside your auth service or component
constructor(private angulartics2: Angulartics2) {}

loginUser(userId: string) {
  this.angulartics2.setUsername.next(userId);
}

Setting User Properties (setUserProperties)

Attach properties to the user's profile. These are often called "user traits". This will merge with existing properties.

this.angulartics2.setUserProperties.next({
  plan: 'premium',
  lastLogin: new Date(),
  userType: 'admin'
});

Setting User Properties Once (setUserPropertiesOnce)

Similar to setUserProperties, but these properties will only be set if they don't already exist on the user's profile (e.g., for tracking the initial sign-up date).

this.angulartics2.setUserPropertiesOnce.next({
  firstLoginDate: new Date()
});

Advanced Usage

Using Without the Angular Router

If your application does not use @angular/router, you can use Angulartics2RouterlessModule. Note that @angular/router must still be installed, but it will not be used for tracking.

import { Angulartics2RouterlessModule } from 'angulartics2';

@NgModule({
  imports: [
    BrowserModule,
    Angulartics2RouterlessModule.forRoot(),
  ],
})

Using With UI-Router

For applications using ui-router, use Angulartics2UirouterModule.

import { Angulartics2UirouterModule } from 'angulartics2';

@NgModule({
  imports: [
    BrowserModule,
    Angulartics2UirouterModule.forRoot(),
  ],
})