@policygenius/lookout
v0.1.0
Published
A frontend client for the scout analytics service
Downloads
38
Maintainers
Keywords
Readme
lookout
Frontend client for scout
analytics service
Table of Contents
Purpose
To provide an easy way for interacting with the Policygenius scout
service in any Javascript application.
It is published as an NPM package under @policygenius/lookout
.
Install
yarn add @policygenius/lookout
Usage
The package is intended to be configured with a base url for the scout
service and then exposes methods to interact with the 3 main endpoints for scout
: identify
, track
, and page
.
You will need to call lookout
with a configuration object each time you want to use one of the exposed methods.
In addition, you will need to call the initialize
method on page load, which ensures that the user is properly identified with scout
before firing off the other exposed methods. You do not need to worry about queueing any lookout
method calls yourself, the initialize
method handles that for you.
import lookout from '@policygenius
const lookoutConfig = {
scoutBaseUrl: 'some-url'
};
// Some where on page load...
lookout(lookoutConfig).initialize();
lookout(lookoutConfig).track('some-event', { some: 'properties' });
lookout(lookoutConfig).identify('some-uuid', { some: 'traits' });
lookout(lookoutConfig).page('some-page', { some: 'properties' });
API
NOTE: This API was built during a hackathon and currently represents a POC for a Javascript client to interact with the scout
analytics service. As scout
becomes ready to be production-ized, this API is subject to change to best fit those needs.
lookout
This is the default export. It is a function that injests a configuration object and exposes methods to interact with the scout
API.
Configuration
An object that you must pass to the lookout
default export each time you plan to use one of the exposed API methods.
scoutBaseUrl
string
| defaults to: '' | required
This provides the url where the scout
analytics service is hosted.
Methods
initialize
Usage:
lookout(lookoutConfig).initialize();
Arguments:
none
This method should be used on page load to make an initial "handshake" with the scout
analytics service. It will ensure a pg-scout-uuid
, which is generated from the scout
analytics service, is stored in localStorage
and queue up subsequent scout
calls to fire later as necessary.
identify
Usage:
lookout(lookoutConfig).identify(userIdentifier: string, traits: object);
Arguments:
userIdentifier | string | required
traits | object
This method is used to make identify
calls to the scout
analytics service. You should use this method when you want to add new identifying traits
to a given user.
You must provide some userIdentifier
, preferably the one generated by scout
, in order to have the passed in traits
associated with the correct user.
track
Usage:
lookout(lookoutConfig).track(eventName: string, properties: object);
Arguments:
eventName | string | required
properties | object
This method is used to make track
calls to the scout
analytics service. You should use this method when you want to track user actions on your site, like button clicks. Best practice is to provide a unique eventName
with any additional metadata concerning the event placed in the properties
argument.
page
Usage:
lookout(lookoutConfig).page(pageName: string, properties: object);
Arguments:
pageName | string | required
properties | object
This method is used to make page
calls to the scout
analytics service. You should use this method when you want to track the different pages a user navigates to.
userAnalyticsId
Usage:
lookout.userAnalyticsId();
This method is used to retrieve the analytics id that has been set as
a result of the initialize
method.