Analytics Forwarder

Forwards analytics events to S3 via API Gateway and Firehose. This repo includes the serverless lambda function for the endpoint, as well as the front-end Javascript SDK.

                                   .:+oooo+:.
                                ./oooooooooooo/
                            `-+oooooooooooooooo
                         .:+ooooooooooooooooooo
                     `-/ooooooooooooooooooooooo         .-`
                  .:+oooooooooooooooooooooooooo         -oo+:.
              `-/ooooooooooooooooooooo+//+ooooo         -oooooo/-`
            `/ooooooooooooooooooooo/-`    `-+oo         -ooooooooo/`
           `+ooooooooooooooooooo:.            .         -ooooooooooo`
           -oooooooooooooooo+:`                         -ooooooooooo-
           -ooooooooooooo/-                             -ooooooooooo-
           -ooooooooooo/                                -ooooooooooo-
           -ooooooooooo-             .:++/.             -ooooooooooo-
           -ooooooooooo-         `-/oooooooo/-`         -ooooooooooo-
           -ooooooooooo-         +oooooooooooo+         -ooooooooooo-
           -ooooooooooo-         +oooooooooooo+         -ooooooooooo-
           -ooooooooooo-         +oooooooooooo+         -ooooooooooo-
           -ooooooooooo-         +oooooooooooo+         -ooooooooooo-
           -ooooooooooo-         `-/oooooooo/-`         -ooooooooooo-
           -ooooooooooo-             .:++:.             -ooooooooooo-
           -ooooooooooo:                                /ooooooooooo-
           -oooooooooooo+:.                          .:ooooooooooooo-
           -oooooooooooooooo/-`                  `-/oooooooooooooooo-
           `+oooooooooooooooooo+:.            .:+ooooooooooooooooooo`
            `/oooooooooooooooooooo+/-`    `-/ooooooooooooooooooooo+`
              `-/+oooooooooooooooooooo+//+ooooooooooooooooooooo+:`
                  .:+ooooooooooooooooooooooooooooooooooooooo/-
                     `-/oooooooooooooooooooooooooooooooo+:.
                         .:+ooooooooooooooooooooooooo/-`
                            `-/oooooooooooooooooo+:.
                                .:+ooooooooooo/-`
                                   `-/oooo+:.

Lambda Installation (Experimental)

To deploy, after installing nvm:

nvm use
npm install -g serverless@1.28.0
npm install
./deploy [ENV]

SDK Usage

Client ID

const tracker = new AnalyticsForwarder({
  keyUrl: <URL_TO_GET_KEY>,
  analyticsUrl: <URL_TO_SEND_ANALYTICS>,
  clientId: <CLIENT_ID>,
  application: 'example',
});

tracker.setUser('1');
tracker.trackEvent('clicked_button', { button_text: 'help' });

Bearer Token

const tracker = new AnalyticsForwarder({
  keyUrl: <URL_TO_GET_KEY>,
  analyticsUrl: <URL_TO_SEND_ANALYTICS>,
  bearerToken: <BEARER_TOKEN>,
  application: 'example',
});

tracker.setUser('1', <BEARER_TOKEN>);
tracker.trackEvent('clicked_button', { button_text: 'help' });

Functions

getFingerprint() ⇒ Promise

Get a fingerprint for the user based on their IP address and user agent. Store the fingerprint as a cookie for when the user returns.

getKey() ⇒ Promise

Get a the tracking key for the user based on the authentication mode. If public is true, use a public client ID to get the key. If public is false, use a bearer token to get the key.

setUser(id, bearerToken) ⇒ Promise

Set the current user to track and identify the user in the analytics.

trackEvent(event, properties) ⇒ Promise

Track an event with certain metadata and properties about the user.

trackException(exception, fatal) ⇒ Promise

Track an exception event with the exception and whether or not it was fatal as properties.

trackPage(page) ⇒ Promise

Track a page event with the name of the page as a property.

getFingerprint() ⇒ Promise

Get a fingerprint for the user based on their IP address and user agent. Store the fingerprint as a cookie for when the user returns.

Kind: global function Returns: Promise - A promise with the fingerprint.

getKey() ⇒ Promise

Get a the tracking key for the user based on the authentication mode. If public is true, use a public client ID to get the key. If public is false, use a bearer token to get the key.

Kind: global function Returns: Promise - A promise with the tracking key.

setUser(id, bearerToken) ⇒ Promise

Set the current user to track and identify the user in the analytics.

Kind: global function

Param	Type	Description
id	String	The id of the user to track.
bearerToken	String	The bearer token for the user for non public tracking.

trackEvent(event, properties) ⇒ Promise

Track an event with certain metadata and properties about the user.

Kind: global function

Param	Type	Description
event	String	The name of the event to track.
properties	Object	Metadata to track about the event.

trackException(exception, fatal) ⇒ Promise

Track an exception event with the exception and whether or not it was fatal as properties.

Kind: global function

Param	Type	Description
exception	String	The exception to track.
fatal	Boolean	Whether or not the exceptionw as fatal.

trackPage(page) ⇒ Promise

Track a page event with the name of the page as a property.

Kind: global function

Param	Type	Description
page	String	The name of the page to track.