@policygenius/lookout

lookout

Frontend client for scout analytics service

Table of Contents

• lookout
• Table of Contents
• Purpose
• Install
• Usage
• API
  • lookout
    • Configuration
      • scoutBaseUrl
    • Methods
      • initialize
      • identify
      • track
      • page
      • userAnalyticsId

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.