Google Analytics plugin for 'Telemetry.js' library
@esri/telemetry-google-analytics> This is a plugin for the Telemetry.js package to send data to Google Analytics using Google Analytics 4.
@esri/telemetry-google-analytics``sh`
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.
`js
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' })
`
`js
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:
`js`
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:
`js
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.
`js
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.