npm package: @policygenius/lookout
Description: A frontend client for the scout analytics service
Author: John Colella
Latest version: 0.1.0

# lookout
Frontend client for `scout` analytics service

# Table of Contents

- [lookout](#lookout)
- [Table of Contents](#table-of-contents)
- [Purpose](#purpose)
- [Install](#install)
- [Usage](#usage)
- [API](#api)
  - [lookout](#lookout-1)
    - [Configuration](#configuration)
      - [scoutBaseUrl](#scoutbaseurl)
    - [Methods](#methods)
      - [initialize](#initialize)
      - [identify](#identify)
      - [track](#track)
      - [page](#page)
      - [userAnalyticsId](#useranalyticsid)

# Purpose
To provide an easy way for interacting with the Policygenius [`scout`](https://github.com/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.

```js

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:**
```js
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:**
```js
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:**
```js
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:**
```js
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:**
```js
lookout.userAnalyticsId();
```

This method is used to retrieve the analytics id that has been set as
a result of the `initialize` method.