# Kutsatira-SDK

[![NPM version](https://img.shields.io/npm/v/angulartics2.svg)](https://npmjs.org/package/angulartics2) [![NPM downloads](https://img.shields.io/npm/dm/angulartics2.svg)](https://npmjs.org/package/angulartics2)
[![MIT license](http://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)


Kutsatira SDK for Angular Applications.

- [Installation](#installation)
  - [Include it in your application](#include-it-in-your-application)
- [Usage](#usage)
  - [Tracking events in templates/HTML](#tracking-events-in-templateshtml)
  - [Tracking events in the code](#tracking-events-in-the-code)
  - [Configuring the Module](#configuring-the-module)
    - [Exclude routes from automatic pageview tracking](#exclude-routes-from-automatic-pageview-tracking)
    - [Remove IDs from url paths](#remove-ids-from-url-paths)
    - [Remove Query Params from url paths](#remove-query-params-from-url-paths)
    - [Remove Hash from url paths](#remove-hash-from-url-paths)
  - [Using Without A Router](#using-without-a-router)
  - [Using With UI-Router](#using-with-ui-router)
  - [SystemJS](#systemjs)
- [Contributing](#contributing)
- [License](#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

```sh
npm install kutsatira-sdk --save
```

### Include it in your application

1. Add `Angulartics2Module` to your root NgModule passing any options desired
```ts
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](#using-without-a-router) or [Using With UI-Router](#using-with-ui-router).

2. __Required__: Import Kutsatira component in the root component. Call `startTracking()` to start the tracking of route changes.
```ts
// 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```:

```ts
// 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

```ts
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.
````ts
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`
````ts
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`
 ````ts
 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`
````ts
Angulartics2Module.forRoot({
  pageTracking: {
    clearQueryParams: true,
  }
}),
````

#### Remove Hash from url paths

`/callback#authcode=123&idToken=456` becomes `/callback`
````ts
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.
````ts
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.  
````ts
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:
```ts
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```:

```ts
// 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:

```ts
// 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](LICENSE)

## Related Projects
+ [angulartics2](https://github.com/angulartics/angulartics2)