README.md

angulartics2

Vendor-agnostic Analytics for Angular Applications. angulartics.github.io/angulartics2

• Installation
  • Include it in your application
• Usage
  • Tracking events in templates/HTML
  • Tracking events in the code
  • Configuring the Module
    • Exclude routes from automatic pageview tracking
    • Remove IDs from url paths
    • Remove Query Params from url paths
    • Remove Hash from url paths
  • Using Without A Router
  • Using With UI-Router
  • SystemJS
• Supported providers
  • For other providers
  • Minimal setup for Google Analytics
• Contributing
• License

Dependencies

Latest version available for each version of Angular

Angulartics2	Angular
8.3.0	8.x
9.1.0	9.x
10.1.0	10.x
11.0.0	12.x
12.0.0	13.x
13.0.0	14.x
latest	15.x

Installation

npm install angulartics2 --save

Include it in your application

1. Add Angulartics2Module to your root NgModule passing any options desired

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouterModule, Routes } from '@angular/router';

import { Angulartics2Module } from 'angulartics2';
import { Angulartics2GoogleAnalytics } from 'angulartics2';

const ROUTES: Routes = [
  { path: '',      component: HomeComponent },
  { path: 'about', component: AboutComponent },
];

@NgModule({
  imports: [
    BrowserModule,
    RouterModule.forRoot(ROUTES),

    // added to imports
    Angulartics2Module.forRoot(),
  ],
  declarations: [AppComponent],
  bootstrap: [AppComponent],
})

Note the different imports when Using Without A Router or Using With UI-Router.

2. Required: Import your providers in the root component. Call startTracking() to start the tracking of route changes.

// component
import { Angulartics2GoogleAnalytics } from 'angulartics2';

@Component({  ...  })
export class AppComponent {
  constructor(angulartics2GoogleAnalytics: Angulartics2GoogleAnalytics) {
    angulartics2GoogleAnalytics.startTracking();
  }
}

Usage

Tracking events in templates/HTML

To track events you can inject the directive angulartics2On into any component and use the attributes angulartics2On, angularticsAction and angularticsCategory:

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

@Component({
  selector: 'song-download-box',
  template: `
    <div 
      angulartics2On="click" 
      angularticsAction="DownloadClick" 
      [angularticsCategory]="song.name">
      Click Me
    </div>
  `,
})
export class SongDownloadBox {}

import { NgModule } from '@angular/core';
import { Angulartics2Module } from 'angulartics2';

@NgModule({
  imports: [
    Angulartics2Module,
  ],
  declarations: [
    SongDownloadBox,
  ]
})

If you need event label, you can use

<div 
  angulartics2On="click" 
  angularticsAction="DownloadClick" 
  angularticsLabel="label-name" 
  angularticsValue="value" 
  [angularticsCategory]="song.name" 
  [angularticsProperties]="{'custom-property': 'Fall Campaign'}">
  Click Me
</div>

Tracking events in the code

import { Angulartics2 } from 'angulartics2';

constructor(private angulartics2: Angulartics2) {
  this.angulartics2.eventTrack.next({ 
    action: 'myAction', 
    properties: { category: 'myCategory' },
  });
}

If you need event label, you can use

this.angulartics2.eventTrack.next({ 
  action: 'myAction',
  properties: { 
    category: 'myCategory', 
    label: 'myLabel',
  },
});

Configuring the Module

Exclude routes from automatic pageview tracking

Pass string literals or regular expressions to exclude routes from automatic pageview tracking.

Angulartics2Module.forRoot({
  pageTracking: {
    excludedRoutes: [
      /\/[0-9]{4}\/[0-9]{2}\/[a-zA-Z0-9|\-]*/,
      '2017/03/article-title'
    ],
  }
}),

Remove IDs from url paths

/project/12981/feature becomes /project/feature

Angulartics2Module.forRoot({
  pageTracking: {
    clearIds: true,
  }
}),

By default, it removes IDs matching this pattern (ie. either all numeric or UUID) : ^\d+$|^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$.

You can set your own regexp if you need to :

/project/a01/feature becomes /project/feature

Angulartics2Module.forRoot({
  pageTracking: {
    clearIds: true,
    idsRegExp: new RegExp('^[a-z]\\d+$') /* Workaround: No NgModule metadata found for 'AppModule' */
  }
}),

Remove Query Params from url paths

This can be combined with clearIds and idsRegExp

/project/12981/feature?param=12 becomes /project/12981/feature

Angulartics2Module.forRoot({
  pageTracking: {
    clearQueryParams: true,
  }
}),

Remove Hash from url paths

/callback#authcode=123&idToken=456 becomes /callback

Angulartics2Module.forRoot({
  pageTracking: {
    clearHash: true,
  }
}),

Using Without A Router

Warning: this support is still experiemental
@angular/router must still be installed! However, it will not be used.

import { Angulartics2RouterlessModule } from 'angulartics2';
@NgModule({
  // ...
  imports: [
    BrowserModule,
    Angulartics2RouterlessModule.forRoot(),
  ],
})

Using With UI-Router

Warning: this support is still experiemental
@angular/router must still be installed! However, it will not be used.

import { Angulartics2UirouterModule } from 'angulartics2';
@NgModule({
  // ...
  imports: [
    BrowserModule,
    Angulartics2UirouterModule.forRoot(),
  ],
})

SystemJS

Using SystemJS? If you aren't using defaultJSExtensions: true you may need to use:

System.config({
    packages: {
        "/angulartics2": {"defaultExtension": "js"},
    },
});

Supported providers

• Google Analytics (analytics.js)
• Google Tag Manager
• Google Enhanced Ecom
• Google Global Site Tag (gtag.js)
• Kissmetrics
• Mixpanel
• Matomo
• Segment
• Baidu Analytics
• Facebook Pixel
• Application Insights
• Hubspot
• Adobe Analytics (Omniture)
• Launch, by Adobe (works with DTM, too)
• Incendium
• Intercom
• Woopra
• Clicky
• IBM Digital Analytics
• Splunk
• Pyze
• Posthog

For other providers

If there's no Angulartics2 plugin for your analytics vendor of choice, please feel free to write yours and PR it!

Minimal setup for Google Analytics

• See Google Analytics if your code snippet contains analytics.js
• See Google Tag Manager if your code snippet contains gtag.js
• See Google Global Site Tag if your code snippet contains gtag.js

Contributing

Please see the CONTRIBUTING and CODE_OF_CONDUCT files for guidelines.

License

MIT

Related Projects

• analytics-angular: Write analytics code once, collect customer data from any source, and send it to over 250+ destinations with Segment.