@esri/telemetry-google-analytics
v2.0.1
Published
Google Analytics plugin for 'Telemetry.js' library
Downloads
2,467
Maintainers
Readme
@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
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.