kutsatira-sdk

Kutsatira-SDK

Kutsatira SDK for Angular Applications.

• Installation
  • Include it in your application
• Usage
  • Tracking events in templates/HTML
  • Tracking events in the code
  • Configuring the Module
    • Exclude routes from automatic pageview tracking
    • Remove IDs from url paths
    • Remove Query Params from url paths
    • Remove Hash from url paths
  • Using Without A Router
  • Using With UI-Router
  • SystemJS
• Contributing
• License

Dependencies

Latest version available for each version of Angular

Angulartics2	Angular
5.4.0	4.x
6.3.1	5.x
7.5.2	6.x - 7.x
8.3.0	8.x
9.1.0	9.x
latest	10.x

Installation

npm install kutsatira-sdk --save

Include it in your application

• 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 'kutsatira-sdk';
import { Angulartics2Kutsatira } from 'kutsatira-sdk/kutsatira';

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.

• Required: Import Kutsatira component in the root component. Call startTracking() to start the tracking of route changes.

// component
import { Angulartics2Kutsatira } from 'kutsatira-sdk/kutsatira';

@Component({  ...  })
export class AppComponent {
  constructor(angulartics2Kutsatira: Angulartics2Kutsatira) {
    angulartics2Kutsatira.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:

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

@Component({
  selector: 'song-download-box',
  template: `
    <div 
      angulartics2On="click" 
      angularticsAction="DownloadClick" 
      >
      Click Me
    </div>
  `,
})
export class SongDownloadBox {}

import { NgModule } from '@angular/core';
import { Angulartics2Module } from 'kutsatira-sdk';

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

Tracking events in the code

import { Angulartics2 } from 'angulartics2';

constructor(private angulartics2: Angulartics2) {
  this.angulartics2.eventTrack.next({ 
    action: 'myAction'
  });
}

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

SystemJS

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

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

Specials Names

To track void events you can add void_ in front of the name of the action in the directive angularticsAction:

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

@Component({
  selector: 'song-download-box',
  template: `
    <div 
      angulartics2On="click" 
      angularticsAction="void_DownloadClick" 
      >
      Click Me
    </div>
  `,
})
export class SongDownloadBox {}

import { NgModule } from '@angular/core';
import { Angulartics2Module } from 'kutsatira-sdk';

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

To track events in step of configurator you can add angularticsAction attribute in the code:

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

@Component({
  selector: 'song-download-box',
  template: `
    <div 
      angulartics2On="click" 
      angularticsAction="DownloadClick"
      angularticsStep="step1"
      >
      Click Me
    </div>
  `,
})
export class SongDownloadBox {}

import { NgModule } from '@angular/core';
import { Angulartics2Module } from 'kutsatira-sdk';

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

License

MIT

Related Projects

• angulartics2