/angulartics2

Vendor-agnostic analytics for Angular2 applications.

Primary LanguageTypeScriptMIT LicenseMIT

angulartics2

NPM version NPM downloads devDependency Status Build Status

MIT license Gitter Chat

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

v4.0.0 Migration and Breaking Changes

See Release Notes

Installation

npm install angulartics2 --save

Include it in your application

  1. 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],
})
  1. 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

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

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

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 ID's from url paths

/project/12981/feature becomes /project/feature

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

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

Add the full Google analytics.js tracking code to the beginning of your body tag.

Changes in the Google Analytics snippet

The snippet code provided by Google Analytics does an automatic pageview hit, but this is already done by Angulartics (unless you disable it) so make sure to delete the tracking line:

      ...
      ga('create', 'UA-XXXXXXXX-X', 'none'); // 'none' while you are working on localhost
      ga('send', 'pageview');  // DELETE THIS LINE!
    </script>

SystemJS

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

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

Contributing

Please see the CONTRIBUTING and CODE_OF_CONDUCT files for guidelines.

License

MIT