angulartics2

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

Installation
- Include it in your application
Usage
Supported providers
- For other providers
- Minimal setup for Google Analytics
v4 Migration and Breaking Changes
Contributing
License

Installation

npm install angulartics2 --save

Include it in your application

Add Angulartics2Module to your root NgModule passing an array of providers to enable

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/ga';

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

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

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

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

Required: Import your providers in the root component. This starts the tracking of route changes.

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

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

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([providers], {
  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([providers], {
  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([providers], {
  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([providers], {
  pageTracking: {
    clearQueryParams: true,
  }
}),

Remove Hash from url paths

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

Angulartics2Module.forRoot([providers], {
  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/routerlessmodule';
@NgModule({
  // ...
  imports: [
    BrowserModule,
    Angulartics2RouterlessModule.forRoot([Angulartics2GoogleAnalytics]),
  ],
})

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/uiroutermodule';
@NgModule({
  // ...
  imports: [
    BrowserModule,
    Angulartics2UirouterModule.forRoot([Angulartics2GoogleAnalytics]),
  ],
})

SystemJS

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

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

Supported providers

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

fastcaseinc/angulartics2