@inyourarea/aard-client-js/README.md

A JavaScript tracking library for the Aard Platform at InYourArea.co.uk. Record and track activity across the different services of the platform.

# Aard Recorder-js

A JavaScript tracking library for the Aard analytics platform at [InYourArea.co.uk](https://inyourarea.co.uk). Record and track activity across the different services of the platform.

## Quick Start
`yarn` to install dependencies

`yarn build` to build the project

`yarn watch` to build the project and watch for file changes

`yarn check:lint` to check the code with tslint

`yarn test` to run unit tests

`yarn test:watch` to run unit tests and watch for file changes

`yarn test:ui` to run and explore unit tests in a web interface

`yarn docs` to generate docs in docs/ folder


### Project Name & API Keys
You will need to provide an API Key and a Project Name to record events to the platform.

## Concepts

### What is an event?
...

### What is a fragment?
...

### What is a transformer?
...

## Usage
...
### UMD standalone version
```html
<!-- development version -->
<script src="https://unpkg.com/aard-client-js/umd/aard-client-recorder.development.js"></script>
<!-- production version -->
<script src="https://unpkg.com/aard-client-js/umd/aard-client-recorder.production.js"></script>
```
...
### Initialization
...
#### Initialize the recorder
```javascript
  import { Recorder } from 'aard-client-js/recorder'

  const recorder = new Recorder({
    apiKey: 'API_KEY',
    projectName: 'project-name',
    environment: 'prod',
  })
```
#### Initialize the recorder with a custom aard server endpoint
```javascript
  import { Recorder } from 'aard-client-js/recorder'

  const recorder = new Recorder({
    apiKey: 'API_KEY',
    projectName: 'project-name',
    environment: 'prod',
    baseUrlCreator: env => `https://custom-aard-endpoint-${env}/`
  })
```
#### Initialize the recorder with debug messages
```javascript
  import { Recorder } from 'aard-client-js/recorder'

  const recorder = new Recorder({
    apiKey: 'API_KEY',
    projectName: 'project-name',
    environment: 'prod',
    debug: true,
  })
```
#### Initialize the recorder with a custom fetch function
```javascript
  import { Recorder } from 'aard-client-js/recorder'

  const recorder = new Recorder({
    apiKey: 'API_KEY',
    projectName: 'project-name',
    environment: 'prod',
    fetchFn: fetch,
  })
```
#### Initialize the recorder without session cookie
```javascript
  import { Recorder } from 'aard-client-js/recorder'

  const recorder = new Recorder({
    apiKey: 'API_KEY',
    projectName: 'project-name',
    environment: 'prod',
    session: false,
  })
```
#### Initialize the recorder with a custom number or retries
```javascript
  import { Recorder } from 'aard-client-js/recorder'

  const recorder = new Recorder({
    apiKey: 'API_KEY',
    projectName: 'project-name',
    environment: 'prod',
    maxRetries: 10,
  })
```
#### Initialize the recorder with specific transformers
```javascript
  import { Recorder }, { transformers } from 'aard-client-js/recorder'

  const recorder = new Recorder({
    apiKey: 'API_KEY',
    projectName: 'project-name',
    environment: 'prod',
    maxRetries: 10,
    transformers: [
      transformers.addBrowserLanguage,
      transformers.addCurrentPageDetails,
      transformers.addPageReferrer,
      transformers.addUserAgent
    ]
  })
```
#### Initialize the recorder with custom transformers
```javascript
  import { Recorder } from 'aard-client-js/recorder'

  const addTwitterAccount = event => ({
    ...event,
    dimensions: {
      ...event.dimensions,
      twitter: {
        name: user.twitterAccount,
        url: user.twitterAccountUrl
      }
    },
    plugins: [
      plugins.parseUrl('twitter.url')
    ]
  })
  const recorder = new Recorder({
    apiKey: 'API_KEY',
    projectName: 'project-name',
    environment: 'prod',
    maxRetries: 10,
    transformers: [
      addTwitterAccount
    ]
  })
```

### Sending Events
...
#### Send normal event
```javascript
  recorder.sendEvent('contentplus', {
    dimensions: {
      advertIid: 'iid',
      version: '1.3.1',
      category: 'event-category'
    }
  })
```
#### Send event with a custom trasformer
```javascript
  import { transformers } from 'aard-client-js/recorder'

  recorder.sendEvent('contentplus', {
    dimensions: {
      advertIid: 'iid',
      version: '1.3.1',
      category: 'event-category'
    }
  }, [
    transformers.addBrowserLanguage
  ])
```
#### Send event with a custom plugin
```javascript
  import { plugins } from 'aard-client-js/recorder'

  recorder.sendEvent('contentplus', {
    dimensions: {
      advertIid: 'iid',
      version: '1.3.1',
      category: 'event-category'
    },
    plugins: [
        plugins.remoteJoin('adverts', 'advertIid', 'advert'),
        plugins.restoreFragment('hash')
      ]
  })
```
or
```javascript
  import { transformers } from 'aard-client-js/recorder'

  recorder.sendEvent('contentplus', {
    dimensions: {
      advertIid: 'iid',
      version: '1.3.1',
      category: 'event-category'
    },
  }, [
    transformers.addRemoteJoinPlugin('adverts', 'advertIid', 'advert'),
    transformers.addRestoreFragmentPlugin('hash')
  ])
```

### Fragments
...
#### Register a fragment in the recorder
```javascript
  recorder.registerFragment('app', {
    app: { version: '1.3.1' }
  })
```
#### Add a fragment hash to the recorder
```javascript
  recorder.addFragmentHash('app', 'hash')
```
#### Remove a fragment hash from the recorder
```javascript
  recorder.removeFragment('app', 'hash')
```

### Dynamically add global transformers
Other then adding global transformers during the recorder initialization or adding transformers for a specific event, you can dynamically add/remove global transformers to the recorder.
```javascript
  import { transformers } from 'aard-client-js/recorder'

  recorder.addTransformer(transformers.addBrowserLanguage)
  recorder.removeTransformer(transformers.addBrowserLanguage)
```

#### Custom transformers
A trasformer is simply a function that takes an event (AardEvent interface) and return an event.

### Advanced Usage
If you want fine control you can get access the low level functions used by the recorder to communicate with the Aard server. These function will not automatically add any fragment plugin or transformer, as well as will not handle the fragment hashes for you.

#### Get the client
```javascript
  recorder.getClient()
```