ngx-analytics
Version:
Vendor-agnostic web analytics for Angular2 applications, based on angulartics2
295 lines (243 loc) • 8.49 kB
Markdown
# ngx-analytics
[](https://npmjs.org/package/ngx-analytics) [](https://npmjs.org/package/ngx-analytics)
[](https://david-dm.org/angulartics/ngx-analytics#info=devDependencies)
[](https://travis-ci.org/angulartics/ngx-analytics)
[](LICENSE)
[](https://gitter.im/angulartics/ngx-analytics)
Vendor-agnostic Analytics for Angular Applications. [angulartics.github.io/ngx-analytics](https://angulartics.github.io/ngx-analytics "Angulartics Docs")
- [ngx-analytics](#ngx-analytics)
- [Installation](#installation)
- [Include it in your application](#include-it-in-your-application)
- [Usage](#usage)
- [Tracking events](#tracking-events)
- [Tracking events in the code](#tracking-events-in-the-code)
- [Exclude routes from automatic pageview tracking](#exclude-routes-from-automatic-pageview-tracking)
- [Remove ID's from url paths](#remove-ids-from-url-paths)
- [Remove Query Params from url paths](#remove-query-params-from-url-paths)
- [Using Without A Router](#using-without-a-router)
- [Using With UI-Router](#using-with-ui-router)
- [Supported providers](#supported-providers)
- [For other providers](#for-other-providers)
- [Minimal setup for Google Analytics](#minimal-setup-for-google-analytics)
- [v4 Migration and Breaking Changes](#v4-migration-and-breaking-changes)
- [SystemJS](#systemjs)
- [Contributing](#contributing)
- [License](#license)
## Installation
```sh
npm install ngx-analytics --save
```
### Include it in your application
1. Add `NgxAnalyticsModule` to your root NgModule passing an array of providers to enable
```ts
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],
})
```
2. __Required__: Import your providers in the root component. This starts the tracking of route changes.
```ts
// 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```:
```ts
// 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
```html
<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
```ts
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
```ts
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.
````ts
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`
````ts
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`
````ts
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`
````ts
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.
````ts
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.
````ts
import { NgxAnalyticsUirouterModule } from 'ngx-analytics/uiroutermodule';
@NgModule({
// ...
imports: [
BrowserModule,
NgxAnalyticsUirouterModule.forRoot([NgxAnalyticsGoogleAnalytics]),
],
})
````
## Supported providers
* [Google Analytics](/src/lib/providers/ga)
* [Google Tag Manager](/src/lib/providers/gtm)
* [Google Enhanced Ecom](/src/lib/providers/ga-enhanced-ecom)
* [Kissmetrics](/src/lib/providers/kissmetrics)
* [Mixpanel](/src/lib/providers/mixpanel)
* [Piwik](/src/lib/providers/piwik)
* [Segment](/src/lib/providers/segment)
* [Baidu Analytics](/src/lib/providers/baidu)
* [Facebook Pixel](/src/lib/providers/facebook)
* [Application Insights](/src/lib/providers/appinsights)
* [Hubspot](/src/lib/providers/hubspot)
* [Adobe Analytics (Omniture)](/src/lib/providers/adobeanalytics)
* [Intercom](/src/lib/providers/intercom)
* [Woopra](/src/lib/providers/woopra)
* [Clicky](/src/lib/providers/clicky)
### 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
```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
```ts
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](https://github.com/angulartics/ngx-analytics/releases/tag/v4.0.0)
## SystemJS
Using SystemJS? If you aren't using `defaultJSExtensions: true` you may need to use:
```ts
System.config({
packages: {
"/ngx-analytics": {"defaultExtension": "js"},
},
});
```
## Contributing
Please see the [CONTRIBUTING](https://github.com/angulartics/ngx-analytics/blob/master/.github/CONTRIBUTING.md) and [CODE_OF_CONDUCT](https://github.com/angulartics/ngx-analytics/blob/master/.github/CODE_OF_CONDUCT.md) files for guidelines.
## License
[MIT](LICENSE)