Ngx-analytics NPM

ngx-analytics

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

ngx-analytics

Installation

npm install ngx-analytics --save

Include it in your application

Add NgxAnalyticsModule 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 { NgxAnalyticsModule } from 'ngx-analytics';
import { NgxAnalyticsGoogleAnalytics } from 'ngx-analytics/ga';

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

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

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

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

// component
import { NgxAnalyticsGoogleAnalytics } from 'ngx-analytics/ga';

@Component({  ...  })
export class AppComponent {
  constructor(ngx-analyticsGoogleAnalytics: NgxAnalyticsGoogleAnalytics) {}
}

Usage

Tracking events

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

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

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

import { NgModule } from '@angular/core';
import { NgxAnalyticsModule } from 'ngx-analytics';

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

If you need event label, you can use

<div 
  ngx-analyticsOn="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 { NgxAnalytics } from 'ngx-analytics';
constructor(private ngx-analytics: NgxAnalytics) {
  this.ngx-analytics.eventTrack.next({
    action: 'myAction', 
    properties: { category: 'myCategory' },
  });
}

If you need event label

this.ngx-analytics.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.

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

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

NgxAnalyticsModule.forRoot([providers], {
  pageTracking: {
    clearIds: true,
    idsRegExp: /^[a-z]\d+$/,
  }
}),

Remove Query Params from url paths

This can be combined with clearIds and idsRegExp

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

NgxAnalyticsModule.forRoot([providers], {
  pageTracking: {
    clearQueryParams: true,
  }
}),

Using Without A Router

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

import { NgxAnalyticsRouterlessModule } from 'ngx-analytics/routerlessmodule';
@NgModule({
  // ...
  imports: [
    BrowserModule,
    NgxAnalyticsRouterlessModule.forRoot([NgxAnalyticsGoogleAnalytics]),
  ],
})

Using With UI-Router

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

import { NgxAnalyticsUirouterModule } from 'ngx-analytics/uiroutermodule';
@NgModule({
  // ...
  imports: [
    BrowserModule,
    NgxAnalyticsUirouterModule.forRoot([NgxAnalyticsGoogleAnalytics]),
  ],
})

Supported providers

For other providers

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

Minimal setup for Google Analytics

To setup Google Analytics add the folowing to main.ts

import {NgxAnalyticsGoogleAnalytics} from "ngx-analytics/ga";


if (environment.production) {
  // ...
  NgxAnalyticsGoogleAnalytics.prototype.createGaSession(environment.googleAnalytics);
}

you can add other environments if you want. In your environment.prod.ts add the configuration

export const environment = {
  production: true,
  // ...
  googleAnalytics: {
    domain: 'auto',
    trackingId: 'UA-XXXXXXXX-X' // replace with your Tracking Id
  }
};

for localhost environments replace 'auto' with 'none'

v4 Migration and Breaking Changes

See Release Notes

SystemJS

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

System.config({
    packages: {
        "/ngx-analytics": {"defaultExtension": "js"},
    },
});

Contributing

Please see the CONTRIBUTING and CODE_OF_CONDUCT files for guidelines.

License

MIT

angular4 angular5 angularx ng4 ng5 ngx angular analytics tracking google analytics google tag manager woopra splunk piwik page tracking event tracking scroll tracking inspectlet

tslib

@everything-registry/sub-chunk-2281 @infinitebrahmanuniverse/nolb-ngx-a

4.6.3-patch1

7 years ago

4.6.2

7 years ago

4.6.3

7 years ago