This is a plugin for the
Telemetry.js
package to send data to Google Analytics using Google Analytics 4.
npm install @esri/telemetry
npm install @esri/telemetry-google-analytics
@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.
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' })
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.
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
If something isn't working, please take a look at previously logged issues first. Have you found a new bug? Create an issue here.
Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.