aard-recorder v0.3.3

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.

Installation

Install this package from NPM Recommended

npm install @inyourarea/aard-recorder --save

Project Name & API Keys

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

Getting Started:

Record an Event

import {events, metrics, Recorder} from '@inyourarea/aard-recorder'
const client = new Recorder({
    projectName: 'PROJECT_NAME',
    apiKey: 'API_KEY'
})

const event = new events.Event("pageview")

client.record(event)

Let's go through this. 1. the client will accept a large array of configuration, but you should provide at least the projectName and apiKey. Without an apiKey, your events will be rejected by the platform. 2. the type (here "pageview") is the only required key to create an event. The event will be recorded as representing 1 "Unit" of whatever observable is being recorded.

Dimensions and metrics

In the example below we add more information to our event:

const event = new events.Event("latency", {
    dimensions: {
    page: {
    url: 'https://inyourarea.co.uk/feed/W36AD/'
    },
    app: 'myAwesomeApp'
}, metrics.Milliseconds(1123))

We've added dimensions to our event. Dimensions allow us to specify our event in more details. On the analytics side, we'll be able to query the event based on those dimensions. Notice that nesting of dimensions is valid.

A metrics is also specified to define the event further.

Event extensions

Passing all the relevant dimensions for an application to an event all the time can be tedious. To facilitate event tracking, let's register some extensions to be added automatically to our events.

First we can register a global extension. Every event recorded will be enriched with this information before submission.

const client = new Recorder({
    projectName: 'PROJECT_NAME',
    apiKey: 'API_KEY'
}, async () => ({
    slowContextualMetadata: await getSlowMetadata(),
    clientId: getClientId,
    theAnswer: 42
}))

This function will be called for each event, its returned value will be merged into the dimensions of the event.

Alternatively we can extend a single event type:

client.extendEvent('pageview', {referrer: document.referrer})

Both global and event type extensions can come in the following flavours:

• simple: provide an object directly with the dimensions you want added. ex:{page: url}
• functional: provide a function to be executed that will provide the object. ex: () => ({page: url})
• async functional: provide an asynchronous function. ex: async () => ({slowDim: await getSlowDim()})

API

Config

Below are all the options available.

Options:

• apiKey: string, required. Identify your application to the gateway. projectName: string required. The name of the project you're collecting the data for.
• url: string. url to the gateway. There should not be any need to modify this for production usage.
• environment: string. Gateway environment to hit. This will make sure your test data do not go pollute your production analytics.
• enabled: boolean. Allows you to disable call to the gateway.
• debug: boolean. Enable/disable logging.
• fetch:(input: string | Object, init?: Object) => Promise<*>. In some use case, you may want to provide your own implementation of the fetch api.
• blacklist: Object. Contains names and conditions to reject events. Use for example to prevent incomplete events from being sent to your record store.
• ignoredEvents: Array<string> List of event types to ignore

below is an example of blacklist:

{
    pageview: [{url: undefined}, {environment: "test"}]
}

The client will reject any pageview event with an undefined url OR test as environment.

Recorder

The Recorder is the client that gives you access to the platform.

• Recorder(config: Object | Config, globalExtension: Extension = {}): constructor.
• Recorder.record(event: Event): Promise<Object>: submits an event to the gateway.
• Recorder.extendEvent(unitType: string, extension: Extension): extends a given event type with additional dimensions.

The Extension type is defined as Extension = Object | () => Promise<Object> | () => Object

Event

• Event(unitType: string, {dimensions: Object, metric: Metric, timestamp?: number}): constructor for events. Timestamp will default to the output of Date.now().
• Event.extendLeft(otherDimensions: Object): Event: Return a new Event with his dimensions merged with the provided dimensions. Merging is recursive. If a dimensions is present in both objects, the otherDimensions take precedence. i.e the event dimension will be replaced. For the opposite behaviour use extendRight.
• Event.extendRight(otherDimensions: Object): Event: Return a new Event with his dimensions merged with the provided dimensions. Merging is recursive. If a dimensions is present in both objects, the original events take precedence. i.e the other dimension will be ignored. For the opposite behaviour use extendLeft.
• Event.toRecord(): Record: Generates the final json object that will be published to the gateway.

Dimensions can be any nested object, with the following restrictions:

• Arrays are not valid dimensions. Array dimensions will be discarded by the gateway.
• Continous variable are currently not supported.

The Record type is defined as:

Record = {
  unitType: string,
  dimensions: Object,
  metric: Metric,
  timestamp: number
}

Metrics

A metric has the form Metric(value: number, unit: string) the following metrics are currently supported:

• Units: default metric. Use for example to record increments in pageviews.
• Percent
• Milliseconds