core-analytics

Encapsulates Snowplow & GTM (Google Analytics) functionality

This component abstracts away the gathering of the various data values needed for Google Analytics (GA) and the setting up of Google Tag Manager (GTM). Once registered and the site is running it will prepare each page with the required GTM head tag for pushing analytics to GA. You can see the GTM tag and any GA data by inspecting the head tag of the page and the dataLayer from the browser console in developer tools. If you exercise all the current functionality you will be able to see the following models {platformData: {…}}, {userData: {…}}, {pageData: {…}} & {event: ...} in the dataLayer.

Benefits

• Single component to record GA data rather than having logic & implementations scattered around in various features.
• Self-sufficient: With only supplying a small amount of data this component will attempt to evaluate, gather and record all the data required (clientside) for the GA models: platformData, userData and pageData.
• Provide the facility to push 'ad-hoc' GA events.
• Allows the consumer to dictate if & when to push analytics to GA.
• Customisation (via options) if the need arises.
• Each method returns the model it attempted to push to GA thus allowing you to view/test what has been constructed within each method.
• Allows extra custom properties to be appended to each GA model by the consumer before the model is pushed to the dataLayer.
• Allows properties to be overridden on each GA model by the consumer before the model is pushed.

Usage

• Install the module using npm or Yarn

  yarn add @justeat/core-analytics

  npm install @justeat/core-analytics

• Import & Register

  core-analytics exposes a simple class that performs various steps in the 'constructor' during initialisation to prepare the service for use. When instantiating the service it allows you to pass in 'options' (see the Options section) that allow you to configure some of the static values that may need to change in your environment In the example below it demonstrates how to declare and instantiate the core-analytics service and how you can create the options to pass into the service;

  import AnalyticService from '@justeat/core-analytics';
  
  const req = this.req; // Get a handle to the current request
  const options = {
    featureName: 'checkout-web',
    locale: 'en-GB',
    id: 'GTM-ABC123X'
  };
  
  const service = new AnalyticService(req, options);

• Methods

  • pushPlatformData()

    Evaluates and gather data for the platformData GA model and pushes it to the dataLayer

    Syntax.

    this.$gtm.pushPlatformData({ featureName: custom-web, locale: en-AU, customFields: { custom1: 'one', branding: 'new20' } });

    Parameters.

    (object) {

    • (string) featureName (optional) (default is whatever was set at the point of registration or whatever was reset using the setOptions() method. You may want to change this if working in on a SPA site and you want to change the feature name everytime the active page changed. Note that this will not persist the value unlike the actions of setOptions() method)
    • (string) locale (optional) (default is whatever was set at the point of registration and if not set at that point then the Options default. Note that this will not persist the value unlike the actions of setOptions() method)
    • (object) customFields (optional) (You may want to overwrite/add fields and this parameter allows you to indicate an object of fields/values that if already present will overwrite and if not then will be append to the model)

    }

    Return value.

    (object) platformData model

    This will be the model constructed and pushed to the datalayer (handy for testing and debugging)

    Notes

    This is ideally only called once per page so it is best suited in the parent page component.

    Example

    ./pages/checkout/index.vue

    <script>
        ...
    
        window.onload = function() {
            this.service.pushPlatformData();
        };
    
        ...
    
    </script>

    ---

  • pushUserData()

    Evaluates and gather data for the userData GA model and pushes it to the dataLayer

    Syntax.

    this.$gtm.pushUserData({ authtoken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..., customFields: { custom1: 'one', role: 'admin' } });

    Parameters.

    (object) {

    • (string) authToken (optional)
    • (object) customFields (optional) (You may want to overwrite/add fields and this parameter allows you to indicate an object of fields/values that if already present will overwrite and if not then will be append to the model)

    }

    Return value.

    (object) userData model

    This will be the model constructed and pushed to the datalayer (handy for testing and debugging)

    Notes

    This is ideally only called everytime the User status changes so it might best suited in a login method.
    The method is very dependant on the authToken parameter and without it the userData model will only contain the anonymous user id.

    Example

    <script>
    
        ...
    
        loggedIn (success) {
            if (success === true) {
                this.service.pushUserData({ authToken: this.authToken });
            }
        }
        ...
    </script>

    ---

  • pushPageData()

    Evaluates and gather data for the pageData GA model and pushes it to the dataLayer

    Syntax.

    this.$gtm.pushPageData({ pageName: accounts sign-up, customFields: { custom1: 'one' } });

    Parameters.

    (object) {

    • (string) pageName
    • (number) httpStatusCode (optional)(only override this if you wish to change the default 200, i.e you may be displaying a custom static 404 page and want to record the value 404 instead of 200 or you may be displaying a successful account creation page and want to record the value 201 rather than 200)
    • (object) customFields (optional) (You may want to overwrite/add fields and this parameter allows you to indicate an object of fields/values that if already present will overwrite and if not then will be append to the model)

    }

    Return value.

    (object) pageData model

    This will be the model constructed and pushed to the datalayer (handy for testing and debugging)

    Notes

    This is ideally called everytime the Page status changes, i.e. new page displayed, orientation changed, etc..

    ---

  • setOptions()

    Overrides the current Option values

    Syntax.

    this.$gtm.setOptions({ featureName: checkout-web, locale: en-IE });

    Parameters.

    (object) {

    • (string) featureName (optional)
    • (string) locale (optional) (default is whatever was set at the point of registration and if not set at that point then the Options default. Note that this method will persist the value) }

    Return value.

    (object) options model

    This will be the current Options model (handy for testing and debugging)

    Notes

    If working in on a SPA site and you want to change the feature name everytime the active page changes then use this method to override the featureName at the same time so all subsequent analytics contain the correct featureName. You may also need to change the current active locale and as such you will need to use this method to reset the locale at the same time so all subsequent analytics contain the correct data.Note that this method will persist the value/s until this method is called again or the plugin is re-registered.

    ---

  • getOptions()

    Gets the current Option values

    Syntax.

    this.$gtm.getOptions();

    Return value.

    (object) options model

    This will be the current Options model.

    ---

  • pushEvent()

    Pushes the given event object to the dataLayer

    Syntax.

    this.$gtm.pushEvent({ event object ... });

    Parameters.

    (object) event

    Return value.

    (object) event model

    This will be the model constructed and pushed to the datalayer (handy for testing and debugging)

    Notes

    This can be called at ad-hoc times to indicate an action, event or status as required by your Analytics team. The shape of the event object will be dictate by your Analylics team If this method is executed serverside then although the event cannot be pushed to GA (because it needs a GTM prepare DOM) it will be store internally until the plugin has re-registered clientside then any stored events will be pushed to GA.

    Example

    <script>
    
        ...
    
            if (isLoggedIn(type)) {
                const loggedInEvent = {
                    event: 'loggedIn-`${type}`',
                    experiment: {
                        id: 'EX-1234',
                        name: 'Some experiment',
                        platform: 'experiment_api',
                        variant: {
                            name: 'increase_a'
                        },
                    version: 1
                    }
                };
    
                this.service.pushEvent(loggedInEvent);
            }
    
        ...
    </script>

Options

Note: although core-analytics gathers most of it's analytical data from within it does rely on some specific values to be supplied by your feature via an options object. See object spec. below:

| Prop Name | Example | Optional/Required | Default | Description | | :--- | :--- | :--- | :--- | :--- | | featureName| 'coreweb' | Required | | This is used to identify analytics sent by your feature | | locale| 'en-GB' | Optional | en-GB | This is used to calcualate various platform data values | | id| 'GTM-X1234Z' | | | This is used know what GA account to push analytics to | | auth| 'authKey' | Optional | | Please speak to your Analytics team for more information about this option | | preview| 'preview id' | Optional (required if auth supplied) | | Please speak to your Analytics team for more information about this option | | cookiesWin| 'x-je-gtm_cookie' | Optional (required if auth supplied) | | Please speak to your Analytics team for more information about this option |

* Note; you don't have to supply the 'options' object (i.e. if testing) but the component will only operate in a limited capacity without it.

Environment variables

Although this component can gather most data with only the options object it also needs some values that may only be available on the serverside. These can be passed in as 'custom' fields. e.g.:

| Prop Name | Type | Example | Description | | :----- | :----- | :----- | :----------- | | environment | Server Environment Variable | staging | This will indicate the current environment | | version | Server Environment Variable | 1.12.345.0 | This will indicate the current version of the feature | | instancePosition | Server Environment Variable | 004 | This will indicate the current position of the AWD EC2 instance | | isPilot | Server Environment Variable | false | This will indicate whether the server is a pilot or not |

Development

Start by cloning the repository and installing the required dependencies:

$ git clone [email protected]:justeat/fozzie-components.git
$ cd fozzie-components
$ yarn
$ yarn build

Change directory to the core-analytics package:

$ cd packages/services/core-analytics

Testing

To test all components, run from root directory. To test only core-analytics, run from the ./fozzie-components/packages/services/core-analytics directory.

Unit tests

yarn test