Jamberoo Analytics Library

The Jamberoo Analytics Library is both a jFrog and Azure DevOps artefact to standardise analytics payloads in our React apps. This abstracts the data model away from the developer. It’s also a transformation layer for the Atomic Design System (ADS), taking analytics payloads from ADS components and converting them so they can be pushed to the dataLayer.

If there is no solution design for this project, please contact Jamberoo Digital Analytics Team.

Local development

To develop new functionality for the Jamberoo Analytics Library, setup and start the demo React app. This app contains a webpage where Jamberoo site tracking events occur such as pageviews, button clicks and modal opens. It enables you to quickly test changes in real-time without the need to deploy a new npm package to prod just to test a new code change. To use the demo app you'll need to link the ./lib folder (located in the root of Jamberoo-analytics-npm package repository) with the demo-typescript app, by creating a symlink using npm link.

To install the demo app, follow these steps:

1. npm i installs the dependencies* of Jamberoo-analytics-npm. (*also see note about Peer Dependencies).
2. npm run compile and check that a ./lib folder was created.
3. npm link will install the ability to create a symlink to a package folder.
4. cd demo-typescript. You should be in the demo app for the next few steps.
5. npm link @Jamberoo/analytics. This will create a symlink between the Jamberoo-analytics-npm package folder and the demo app.
6. npm i install the dependencies of the demo app.
7. npm run start to start the demo app.

Test changes to the NPM package in the demo app:

1. npm run compile:watch in root of Jamberoo-analytics-npm.

Note about Peer Dependencies

If your version of NPM is between v3 - v6+ (npm -v to check), peer dependencies are not installed automatically, and when installing Jamberoo-analytics-npm package dependencies, you'll receive warnings such as "You must install peer dependencies yourself". You can try doing this, but it's best if you simply upgrade to NPM 7+.

React implementation

The currently supported implementation is using React. To the consumer the library exposes a hook/Provider with a component of the consumers' choice.

App.tsx (Provider)

/**
 * @param {String} brand
 * @param {String} region
 * @param {String} environment
 * @param {String} appName
 * @param {String} appPartner
 * @param {Object} initialData
 * @param {Boolean} isAuthenticated
 * @param {String} basePageId
 * @param {String} state
 * @param {String} gaVersion
 * @param {Boolean} shouldReset
 * shouldReset is a boolean hook that is used to know
 * when to reset/clear current site tracking session data.
 * This is passed in from the consumer as all touch points of
 * when to do so is not the responsibility of the library
 */

<AnalyticsWrapper
  brand="Jamberoo" // Current Brand, such as Jamberoo Direct, Elders
  region="au" // au, nz
  environment={process.env.NODE_ENV} // Node Environment
  appName="npmDemoApp" // appName is a restricter process variable to force developers engage with MAIA team before using this npm package
  appPartner="Jamberoo Direct" // Partners such as, AuPost, Elders
  initialData={{ ...globalData }} // InitialData - is for the global data points fire on every single dataLayer.push
  isAuthenticated={false} // Optional - if isAuthenticated is set true, it will automatically amended the pageId or argument a data point (future proof)
  basePageId="/quote/happy-demo" // basePageId is the common base page Id
  state="" // Optional - to added value to the state data point.
  shouldReset={true} // ShouldReset - refers to the application will reset when it is refresh, it clears all the site tracking pending quests in the queue.
>
  <div className="App">
    <p>Your application</p>
  </div>
</AnalyticsWrapper>

Components

Virtual Page view Tracking

Pageview tracking is an event that is fired on every page load within your application. It's a fundamental aspect of web analytics and is commonly used to gather data about website traffic, user engagement, and the popularity of specific web pages. Pageview tracking helps website owners and marketers understand how users interact with their website, which pages are most visited, and how visitors navigate through the site.

For example:

import { analytics } from '@Jamberoo/analytics';

analytics.trackPageView({
  virtualPagePath: 'page01',
  data: {
    ...dataPoints,
    transactionStartView: true, // Triggers an additional event when the user initiates a transaction, indicating the start of the transaction view.
    quoteStartView: true, // Triggers an additional event when the user starts viewing a quote, signaling the beginning of the quote view process.
    buyStartView: true, // Triggers an additional event when the user begins viewing the purchase options, marking the start of the buy view process.
    quoteComplete: true, // Fires an event when a user completes a quote, requires the 'quoteNumber' data point. This event is deduplicated and fires only once.
    buyStart: true, // Initiates an event when the user starts the purchase process, 'quoteNumber' is necessary. This event is deduplicated and fires only once.
    purchase: true, // Generates an event when a purchase is made, requires 'quoteNumber', 'policyNumber', and 'ecommerce' data. This event is deduplicated and fires only once.
    ecommerce: {} // E-commerce object required for the 'purchase' event. Refer to specific data points for the appropriate ecommerce types.
    appStart: true, // Should be included on the initial page of a Single Page Application (SPA), indicating the start of user interaction with the app.
    appComplete: true // Should be placed on the final page of the SPA, signifying the completion of user interaction with the app.
  },
});

Events Tracking

For Interaction or event tracking. It is essential to use event tracking. It provides capability to understand how users engage with the application. In addition, event tracking could also target specific event, such a business error or technical error, furthermore developer could create their custom event to fulfil their specific requirements.

import { analytics } from '@Jamberoo/analytics';

Methods, signatures and examples use

Custom Event

analytics.trackCustomEvent({
  event: 'event name' // @param {String}
  eventAction: 'event action', // @param {String}
  eventLabel: 'some event Label', // @param {String}
  data: {
    // @param {Object}
    dataPoint: 'Some data points',
  },
});

Business Error

analytics.trackBusinessError({
  errorCode: 'BA-13', // @param {String},
  questionId: 'Liability Limit' // @param {String},
  message: 'Liability limit is over 5 million' // @param {String}
})

Technical Error

analytics.trackTechnicalError({
  errorCode: '503', // @param {String},
  message: 'API Gateway is currently not available', // @param {String},
  technicalErrorType: 'API errors', // @param {String},
  errorType: 'technical', // @param {String},
});

Tools

The analytics package also included several helper functions within the tools object.

1. tools.normalisedHashAddress()

Hashing the full address for the digital footprint. Confluence: https://Jamberoo-appservices.atlassian.net/wiki/spaces/WA/pages/2379284505/Normalised+Hash+Address

Description: The nromalisedHashAddress process the address with these rules and return a SHA256 encrypted value.

• Address attributes will be order as the below sequence.

  1. Street Number (e.g. 169-171)
  2. Street Name (e.g. norton)
  3. Street Type (e.g. st)
  4. Suburb (e.g. leichardt)
  5. State (e.g. nsw)
  6. Postcode (e.g. 2040)

• Characters will transform into lowercase.

• Strings spaces will be removed.

• Street type will be abbreviated (e.g. ‘rd’, not 'road').

  | Street Type | Abbreviation | | ----------- | ------------ | | alley | ally | | arcade | arc | | avenue | ave | | boulevard | bvd | | bypass | bypa | | circuit | cct | | close | cl | | corner | crn | | court | ct | | crescent | cres | | cul-de-sac | cds | | drive | dr | | esplanade | esp | | green | grn | | grove | gr | | highway | hwy | | junction | jnc | | lane | lane | | link | link | | mews | mews | | parade | pde | | place | pl | | ridge | rdge | | road | rd | | square | sq | | street | st | | terrace | tce |

• Removal of the following characters:

  • ,
  • :
  • -
  • _
  • (
  • )
  • '
  • /
  • .

Code Example

import tools from 'Jamberoo/analytics';

tools.normalisedHashAddress({
  streetNumber: '388',
  streetName: 'George',
  streetType: 'Street',
  suburb: 'Sydney',
  state: 'NSW', // NSW | ACT |  NT | SA | WA | TAS | QLD | VIC
  postCode: '2000',
});

// Return SHA256 value  as  "eef799ca09574f3cb261b80e0e759117f7fb039ad7d30155c5f65ba589db4626"

2. tools.hashingHandler()

Description: SHA256 helper function to generate SHA256 encrypted string.

Code Example

import tools from 'Jamberoo/analytics';

tools.hashingHandler('Jamberoo Insurance');

// Return SHA256 value  as  610be71b1131cfa852344856db87f21273b75267c6814b04c6e0c6c21cb5be5e"

Testing

1. Log Testing

The Analytics NPM package is included logger feature. In order to turn on logger feature, testers need to copy the snippets below in the browser console and refresh the page.

localStorage.setItem('analytics-logger-enabled', true);

This snippet is a browser local storage item. Normally the npm package would not show any log information in the browser console, however once this turns on. It will show all the dataLayer log, it is ultimately easier for testers to identify what have been sent to the dataLayer.

2. Google Measurement Plan Checker

The Analytics NPM package ge also has implemented the Google Spread sheet API for developers and testers validating the the data points. Data Points are referring the object keys within the data object within the dataLayer. Code Example

dataLayer: {
  data: {
    productType: 'HPK,
    policyType: 'I - Home Cover Prestige',
  }
}

Explanation: Explanation: Only the valid data point key names' data will send to Google Analytics, and Google Analytics will ignore the invalid key names' data and WILL NOT SEND to Google Analytics.

Google Spreadsheet API Service

The Google Spreadsheet API Service is built in the analytics package, it validates every single data points' key in the data object.

Code example

const GSHEET_CONFIG = {
  CLIENT_ID:
    '566213614302-vicv4bi31ho2dbe5nht571nn5jnuddon.apps.googleusercontent.com',
  API_KEY: 'AIzaSyDMQ4pIqmb5rTe73uutYp4UKBqJfdLH39Y',
  DISCOVERY_DOCS: ['https://sheets.googleapis.com/$discovery/rest?version=v4'],
  SCOPES: 'https://www.googleapis.com/auth/spreadsheets.readonly',
};

window.sessionStorage.setItem(
  'JamberooGoogleAuth',
  JSON.stringify(GSHEET_CONFIG)
);

Insert this snippet in the browser's console. This snippet is a credential token. the Analytics NPM package will do the API calls to the Google SpreadSheet API Service. The Digital Analytics team has hosted a list of valid data point keys in the Google Spreadsheet.

The analytics package will log valid and invalid data points' keys with different colour codes and log messages.