Skip to content

Latest commit

 

History

History
313 lines (254 loc) · 8.87 KB

README.md

File metadata and controls

313 lines (254 loc) · 8.87 KB
Raw

angulartics2

NPM version NPM downloads Build Status MIT license

Gitter Chat

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

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
latest 13.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.

  1. 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

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

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.