react-common-gdlv2 v1.1.7

react-common-gdlv2

Initialize

Import the react-common-gdlv2 into your react platform. react, react-dom and react-router-dom should also be installed.

Install the react-common-gdlv2 package

npm install react-common-gdlv2

Update index.js

Import GDLV2 and DataLayerProvider from react-common-gdlv2

import { GDLV2, DataLayerProvider } from "react-common-gdlv2";

Create the pageData configuration for each of your routes

You can use wild card in path using .*

const pageData = {
  '/': {
    name: "Home",
    type: "HOME",
    product: {
      name: "My top product",
      id: "123av",
      category: {
          code: "cat1",
          name: "Product category 1"
      }
    },
    section: "Site section 1",
    application: {
      type: "app-agreement",
    },
    form: {
      start: {
        name: "disclaimer",
        blacklist: [ROUTES.APPLICATION_SUMMARY],
      },
      complete: {
        names: ["aboutYou"],
      },
    },
  },
}

Create the GDLV2 instance

const gdlv2 = GDLV2({
  server: "Unique Platform Name",
  brands: {
    ['my.domain.com']: "brand1",
    ['my.domain2.com']: "brand2",
  },
  applicationDetails: {
    "my-application-id1": "My product journey application"
  },
  queryParamsBlacklist: ['token'],
  pageData: pageData
});

Debugging

By default logging will be disabled. To enable logging for the GDLV2 implementation you will need to use setDebug function from the GDVL2 instance

const gdlv2 = GDLV2({...});
gdlv2.setDebug(true)

You can also enable it using localStorage:

localStorage.setItem('gdlv2_debug', true)

Add DataLayerProvider and specify the GDLV2 instance created

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(
  <Router>
    <DataLayerProvider instance={gdlv2}>
      <App />  
    </DataLayerProvider>
  </Router>
);

Update App.js

Import usePageViews and useDataLayer hooks from react-common-gdlv2

import { usePageViews } from 'react-common-gdlv2'

Get config from useDataLayer and call usePageViews

const App = () => {
  //GDLV2 instance config
  const { getConfig } = useDataLayer()
  //Automatic page level tracking powered by pageData config
  usePageViews(getConfig())

  return (
    ...

Load you application in the browser

You should now see the following logs being displayed

🐼 Initialising data layer...
🐼 Data Layer initialized {version: 'v2.5.0', page: {…}, server: {…}, user: {…}, site: {…}, …}
🐼 Page changed {pathname: '/', search: '', hash: '', state: null, key: 'default'}
🐼 Notify PAGE LOAD for path / and config 

Instance methods

The following methods can be used in all application as long as DataLayerProvider is implemented

getConfig()

getConfig() method should be used to retrieve the configuration passed to the GDLV2 instance.

getUtils()

getUtils() methods should be used to retrieve utility methods that will allow you to update the data layer content. You can use the exposes DATA_LAYER_PATH, APPLICATION_SCOPE and APPLICATION_DECISION with the methods to get, set or delete property.

The following utility methods are returned:

• getObjectProperty: retrieve the value of an object property if exist
• setObjectProperty: set the value of an object property and will create all nodes in the property path if not present
• deleteObjectProperty: delete the property of an object.
• updateAttributes: update the attributes array property of the data layer.

trackPage(location)

Should be used to manually track a page in the event the page is displayed without route change

location should be the react router location object

track(name, element, pageSection)

Should be used to track cuustom ACTIONS on the site, like lick on specific DOM element or specific ACTIONS that do not fall in FORM, APPLICATION or PAGE events

• name: custom action name. Should be unique. In the event the action has a dynamic value make sure to only provide a generic value to allow to report on specific action as a whole
• element: object representing DOM element interacted with
  • id: Element DOM id
  • className: Element DOM className
  • type: Element DOM type, should be the type assigned to the element in the DOM
  • value Elemet DOM value, SHOULD BE NON PII DATA
  • category Element category. (i.e: button, accordion)
  • link Link details, should only be populated if element is some sort of a link
    • destination Link destination, should be one fo "External", "Internal", "On-page (no page reload)", ""
    • url Link URL
• pageSection Section of the page where the DOM element is located

trackFormStart(id, name)

To track form start manually. Should only be used if a page change occures without route change

trackFormComplete()

To track form complete manually in the event form complete should be fired before next route

Instance payload

server String

The server property should be specified. Unique value that identifies your platform. Can be a code name which is known across the business.

pageData Object

Data Layer configuration on route change

You will need to configure what needs to be updated in the data layer when a specific route is navigated to. You can specify:

• page data
• form data
• application data
• product data

The formart of each route config is as follow

{
    "/route/path": {
        name: "",
        type: "",
        section: "",
        form: {
            start: {
                name: "Form ID/Name",
                blacklist: ["list", "of", "routes", "which", "cannot", "start", "form"]
            },
            complete: {
                names: ["ids", "of", "form","name.ids", "to", "complete"]
            }
        },
        application: {
            type: "type of application will indicate that application property will need to be updated",
            start: true,
            complete: true
        },
        product: {
            productId: {
                name: "product name",
                id: "product id",
                category: {
                    code: "product category code",
                    name: "product category name"
                }
            }
        }
    }
}

You can provide route with wild card. This should be an exact match and wild card will omit any / in value when evaluating.

Example

const pageData = {
  "/product/.*": {}
}

The above will match:

• /product/12314564

The above will not match:

• /product/1231/
• /product/1231/123
• /previous/product/1231

Page data

You should add the following properties:

• name: correspond to the page name, should be unique. (no need to add page in the value: i.e: Summary instead of Summary page)
• type: correspond to the page type. Several pages can share the same page type i.e: SUMMARY can be shared by all pages that are used to summarise information
• section: correspond to the site section.

Product data

List all of the products present on the page load. The product property is an Object. List of properties to provide:

• name: product name
• id: product id
• category: product category details
  • name: product category name
  • code: product category code

Why use ID and product category code ? Product name and category name can change overtime but ids and code will usually stay the same. At the tagging level we usually will use id and code so the implementation is as stable as possible overtime.

Form data

In the event the page will start a form we can specify which form it starts and we can also control when it will start. For example in the event you application has a back button or an edit button on the summary page we do not want to start the form again so we will add these routes to the blacklist.

NOTICE: you can add both the start and complete properties. A route can be the start of a specific form but also the logic next step to a successful form completion

Properties:

• start: should be added if the route starts a form
  • name: name or ID of the form to start
  • blacklist: (optional) array of routes that should never start the form on this page. i.e: customer comming back to our page via back button or from summary page once clicking on edit button
• complete: should be added if the route is the logical next route to a previous form completion
  • names: array of forms to complete is currently open in data layer

Application data

Here application does not refer to your platform but to the fact the customer started a journey to apply for a platform or a journey which has multi step which results in approved or declied outcome.

Properties:

• type: Application type value will be used as is in the data layer. It also allows to open, monitor and clean up any applications. Should be added to any routes that are part of a specific application
• start: should be set to true if specific route is start of the application type
• complete should be set to true if specific route is end of the application type
• getApplicationID can be provided to return an application ID. This should be a function
• updateMetaData can be provided to update meta data about application. Can also be used to update other sections of the data layer. this can be used to update cards, loan, mortgages etc... application properties
• updateDecisionData can be provided to update the application decision in the status section.

If the customer comes from routeX which has application type ABC and then moves to routeY which does not have application type ABC specified then the application object will be closed automatically.

brands

Object containing key/value pair:

{
    ['my.domain.com']: "brand1",
    ['my.domain2.com']: "brand2",
}

applicationDetails

Object containing key/value pair:

{
    "my-application-one": "My products application"
}

Will be used to populate the application object of the data layer

queryParamsBlacklist

List of query parameter names we do not want to track. Should be an array of string