@mrporter/inseason-analytics

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) 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.

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 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 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. 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.

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

setTransaction(newProps)

setTransaction updates the transaction object. Specification

setWishlist(newProps)

setWishlist updates the wishlist object. Specification