@esri/telemetry-google-analytics

This is a plugin for the Telemetry.js package to send data to Google Analytics using Google Analytics 4.

Table of Contents

• @esri/telemetry-google-analytics
  • Table of Contents
  • Installation
  • How to Use
    • Browser
    • Server
  • Google Analytics Configuration
  • Issues
  • Contributing
  • License

Installation

npm install @esri/telemetry
npm install @esri/telemetry-google-analytics

How to use

@esri/telemetry-google-analytics package works in the client-side browser and server-side Node.js. To use, install the package, include it in your project, create an instance of the plugin, and add it to the plugins array with @esri/telemetry

Below is an example of how to use the browser plugin.

Browser

import { Telemetry } from '@esri/telemetry'
import { GoogleAnalytics } from '@esri/telemetry-google-analytics'

const googleAnalyticsTracker = new GoogleAnalytics({
  measurementIds: [...], // required: fill in measurementIds
  metrics: {}, // optional
  dimensions: {} // optional
})

const telemetryOptions = {
  plugins: [googleAnalyticsTracker],
  portal: {
    subscriptionInfo: {},
    user: {},
  },
}

const telemetry = new Telemetry(telemetryOptions)
await telemetry.init();

telemetry.logPageView({page: 'home'}) // Required
telemetry.logEvent({
  action: 'Dataset', // Required, or will become 'other'
})


telemetry.logPageView({ page: 'home', event: {duration: 60, serviceQuery: 19 }})
telemetry.logEvent({ action: 'Dataset', duration: 4, datasetID: 'ID-XXXXXXX' })

Server

import { Telemetry } from '@esri/telemetry';
import { GoogleAnalytics } from '@esri/telemetry-google-analytics';

const googleAnalyticsTracker = new GoogleAnalytics({
  measurementIds: [...], // required: fill in measurementIds
  metrics: {}, // optional
  dimensions: {} // optional
});

const telemetryOptions = {
  plugins: [googleAnalyticsTracker],
  portal: {
    subscriptionInfo: {},
    user: {},
  },
};

const telemetry = new Telemetry(telemetryOptions);

const scriptTags = telemetry.getScriptTags();

After initializing Telemetry.js with the telemetry-google-analytics plugin, telemetry data will be sent to the Google Analytics 4 instance associated with the provided Measurement ID.

Custom Metrics and/or Custom Dimensions (Optional)

To use custom metrics or custom dimensions, you will need to pass in the metrics and dimensions when you create your instance of GoogleAnalytics. Each should be in the format of dimensionName: Index and metricName: Index, like so:

const googleAnalyticsTracker = new GoogleAnalytics({
  dimensions: {
    datasetID: 1,
    attribute: 2,
    serviceQuery: 3,
  },
  metrics: {
    duration: 1,
    size: 2,
  },
});

Later, when you call logPageView and logEvent and would like to refer to these custom metrics, you can pass them in within the event data in the format of metricName: metricAmount and dimensionName: dimensionValue, like so:

googleAnalyticsTracker.logPageView({page: 'homepage', event: {duration: 30, serviceQuery: 1}});

googleAnalyticsTracker.logEvent({ action: 'Dataset', duration: 20, datasetID: 220130});

If you need to disable tracking you can set disabled: true when initializing the Telemetry object. Then you can continue to call the methods on your instance of Telemetry without throwing exceptions or logging errors.

Post initialization, it is possible to disable & enable specific trackers using disableTracker and enableTracker methods.

telemetry.disableTracker('googleAnalytics');

telemetry.logPageView(); // no google analytics page view logged

telemetry.logEvent(); // no google analytics event logged

telemetry.enableTracker('googleAnalytics');

telemetry.logPageView(); // google analytics page view logged

telemetry.logEvent(); // google analytics event logged

Issues

If something isn't working, please take a look at previously logged issues first. Have you found a new bug? Create an issue here.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

License