Use middleware with Analytics Providers

Middleware allow Analytics Providers to access information within a tenant's page, replacing the legacy custom Metrics systems and metadata providers.

This article describes the workflows to use middlewares for analytics providers.

Living standard

The workflows described in this article are subject to change as the rollout progresses. Ask BERG if you have any doubt!

Declare a middleware

Use the field middleware within the provider's analytics.json configuration:

{
  "googleanalytics": [
    {
      "vars": {
        "account": "XXXXXXXX"
      },
      "touchVars": {
        "environment": "#{env.device.environment}"
      },
      "triggers": {
        "triggerTest": {
          "on": "visible",
          "action": "pageview"
        }
      },
      "middleware": "ugaCustomEvents"
    }
  ]
}

Create the middleware file:

awesome.com/
  └── index/
    └── src/
      └── middlewares/
        └── analytics/
          └── ugaCustomEvents/
            └── on-browser.ts

The value declared in the middleware field must match the folder name that contains the implementation.

A middleware is a Typescript class, and implements one of two methods:

• onBrowser
• onExtraction

Which determines if it is executed during extraction time or during rendering time.

Example

With the following analytics.json configuration:

{
  "googleanalytics": [
    {
      "middleware": "ugaCustomEvents",
      "vars": {
        "account": "UA-XXXXX-X"
      },
      "touchVars": {
        "environment": "marfeel_browser"
      },
      "extraUrlParams": {
        "cd1": "myValue",
        "cd2": "anotherValue"
      },
      "triggers": {
        "triggerTest": {
          "on": "visible",
          "action": "pageview"
        }
      }
    }
  ]
}

And the following middleware/ugaCustomEvents/index.ts:

function extractCDInformation(window): string {
  // some logic inside
  return 'renderTimeExtracted'
}

export const onBrowser = ({ window }) => {
  return {
    extraUrlParams: {
      'cd3': `${extractCDInformation(window)}`
    }
  };
};

The final googleAnalytics object is:

{
  "googleanalytics": [
    {
      "middleware": "ugaCustomEvents",
      "vars": {
        "account": "UA-XXXXX-X"
      },
      "touchVars": {
        "environment": "marfeel_browser"
      },
      "extraUrlParams": {
        "cd1": "myValue",
        "cd2": "anotherValue",
        "cd3": "renderTimeExtracted"
      },
      "triggers": {
        "triggerTest": {
          "on": "visible",
          "action": "pageview"
        }
      }
    }
  ]
}

The new cd3 field was merged in the analytics' configuration.