npm package: @mrporter/inseason-analytics
Description: In Season Analytics Module
Author: Thomas Williams
Latest version: 1.1.0

# In Season Analytics Module

This module aims to provide a single point of interaction for developers implementing analytics in front end applications. There is no need to also include the Web Analytics script.

## Setup

Get the goods:
```npm install --save @mrporter/inseason-analytics```

Import the functions you need (for example):
```import { trackEvent, trackPage } from '@mrporter/inseason-analytics';```

## TL; DR

To set up the analytics in your application:

- Set the page object according to the spec for your page using `setPage`. This module has already set up some parameters. You need to add:

```
setPage({
    pageInfo: {
        pageName,
        environment,
        destinationURL,
        pageType,
        primaryCategory,
        subCategory1,
        subCategory2
    },
    attributes: {
        featuresList // check the page level spec for this, probably not needed
    }
});
```

- Set any other objects according to the spec for your page, e.g. use `setProduct` ([spec](#setproductnewprops)) on the product page, `setTransaction` on the order confirmation page, `setWishlist` on the wishlist page. The `user` object has been set by site furniture, if you need to modify it at any point you can use `setUser`.

- Call `trackPage` after these have been set.

- Use `trackEvent` to track any events on your page according to the spec.

- If you're building a one page app and need to track new pages, you can use the provided functions to make any changes to the digital data object, and then call trackPage again.

## Event and Page Tracking

There are two tracking functions provided. Various steps have been taken to avoid race conditions being an issue (e.g. between your app and site furniture), so just import these and use as necessary:

### trackEvent(eventData)
This calls the Web Analytics `NAP.WebAn.trackEvent` function, and adds the event to the digital data object's `event` array. `eventData` is an object - the format of each of the events can be found on the [web analytics confluence page](https://confluence.nap/display/WEBAN/Tracking+2.0).

Example usage:

```
trackEvent({
    eventInfo: {
        eventName: 'add to cart',
        effect: 'update cart'
    },
    category: {
        primaryCategory: 'ecommerce',
        subCategory: 'productPage'
    },
    attributes: {
        pageNum: 1
    },
    item: [{ ... }]
});
```

(`item` is in the same format as the [product](#setproductnewprops) array below)

### trackPage()
This calls the Web Analytics `NAP.WebAn.trackPage` function, and sends the digital data object (excluding the `event` array) from the current page. Use this on an initial page load after adding anything necessary to the digital data object, or at a relevant time in a single page application.

## Production Mode

This module follows the same convention as React for usage in production mode - it checks that `process.env.NODE_ENV` is set to `production`. (See [here](https://webpack.js.org/guides/production-build/#node-environment-variable) for how to do this with webpack).

## 'Digital Data Object' Manipulation

This digital data object lives on the window and has up to six keys in the following format:

```
window.digitalData = {
    page: { ... }, // page information (every page)
    user: { ... }, // user data (every page)
    cart: { ... }, // where a cart is shown
    product: [{ ... }], // on a product page (this is an array that contains one item)
    transaction: { ... }, // on the order confirmation page
    wishlist:{ ... } // on the wishlist page
}

```

This module sets some of the `page` data where it is consistent, and Site Furniture sets the `user` data. The following methods merge more data into the digital data object, without replacing these initial values (unless you explicitly overwrite a value). In each case, `newProps` is an object containing the data that you wish to add to the digital data object.

### setPage(newProps)
The specification for the `page` object can be found [here](https://confluence.nap/pages/viewpage.action?pageId=18617632).
This module will have set the following properties:

- `pageInfo.sysEnv`
- `pageInfo.language`
- `pageInfo.geoRegion`
- `pageInfo.referringURL`
- `attributes.businessName`
- `attributes.region`
- `attributes.currencyCode`
- `attributes.externalCampaign`
- `attributes.internalCampaign`

`setPage` can then be called in the following format:

```
setPage({
    pageInfo: {
        pageName,
        environment,
        destinationURL,
        pageType,
        primaryCategory,
        subCategory1,
        subCategory2
    },
    attributes: {
        featuresList // check the page level spec for this, probably not needed
    }
});
```

### setUser(newProps)
The specification for the `user` object can be found [here](https://confluence.nap/display/WEBAN/The+User+object+-+attributes+about+the+customer).

Site Furniture will set this on page load. If your app changes user state you can update the data object using this function.

Example usage:

```
setUser({
    profileInfo: {
        // these both come from seaview - not currently available in MRP
        profileId,
        returningStatus
    },
    attributes: {
        status,
        accountID,
        customerCategory,
        customerClass,
        gender,
        preferences: [ designerList ] // this is a 'nice to have'
    }
});
```

### setProduct(newProps)
On the product page, there is an array called `product` which only contains one element, which is an object representing the product on that page. `setProduct` updates that product object.

Example usage:

```
setProduct({
    productInfo: {
        productID,
        sku,
        productName,
        manufacturer,
        manufacturerID
    },
    category: {
        primaryCategory,
        subcategory1,
        subcategory2
    },
    quantity,
    price: {
        currency,
        baseFullPrice,
        basePrice
    },
    attributes: {
        categoryIdList,
        promotionsList,
        saleFlag,
        discountPercent,
        productStock,
        alertsList,
        productFindingMethod
    }
});
```

The following three objects contain an array called `item`, which are all of the items within that cart, order confirmation page, or wishlist respectively. Passing a new item array into this object using these methods will overwrite a previous array, rather than merging with it.

### setCart(newProps)
setCart updates the cart object.
[Specification](https://confluence.nap/display/WEBAN/The+Cart+object+-+attributes+about+the+customer%27s+basket)

### setTransaction(newProps)
setTransaction updates the transaction object.
[Specification](https://confluence.nap/display/WEBAN/Order+Confirmation+Page+-+Tracking)

### setWishlist(newProps)
setWishlist updates the wishlist object.
[Specification](https://confluence.nap/display/WEBAN/Wish+List+-+Tracking)