Aard Recorder-js

A JavaScript tracking library for the Aard analytics platform at 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

<!-- 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

  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

  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

  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

  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

  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

  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

  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

  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

  recorder.sendEvent('contentplus', {
    dimensions: {
      advertIid: 'iid',
      version: '1.3.1',
      category: 'event-category'
    }
  })

Send event with a custom trasformer

  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

  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

  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

  recorder.registerFragment('app', {
    app: { version: '1.3.1' }
  })

Add a fragment hash to the recorder

  recorder.addFragmentHash('app', 'hash')

Remove a fragment hash from the recorder

  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.

  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

  recorder.getClient()