`@esri/telemetry-google`

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

@esri/telemetry-google

Installation

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

How to Use

@esri/telemetry-google 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 { Google } from '@esri/telemetry-google'

const googleTracker = new Google({
  ...
})

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

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

telemetry.logPageView()
telemetry.logEvent({
  category: 'Dataset', // Required
  action: 'Attribute Inspect', // Required
})

Server

telemetry-google requires universal-analytics@0.4.23 package to send data from Node.js. Simply import universal-analytics in your project and initialize it. When logging an event, action and category are required.

Example below:

import { Telemetry } from '@esri/telemetry';
import { Google } from '@esri/telemetry-google';
import ua from 'universal-analytics';

const googleTracker = new Google({
  uaTracker: ua('UA-1234567'), // Required for server
});

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

const telemetry = new Telemetry(telemetryOptions);

telemetry.logPageView();

telemetry.logEvent({
  category: 'Dataset', // Required
  action: 'Attribute Inspect', // Required
});

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

Google Analytics Configuration

Follow instructions on getting started with Google Analytics
Pass in an object containing the mapping for your custom dimensions and metrics
- Read here about custom dimensions and metrics

// or if you are using optional custom dimensions and/or custom metrics
const googleTracker = new Google({
  dimensions: {
    datasetID: 1,
    attribute: 2,
    serviceQuery: 3,
  },
  metrics: {
    duration: 1,
    size: 2,
  },
});

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.

Additionally, you can disable individual trackers when initializing the Telemetry object by passing disabled: true in the tracker options.

const googleTracker = new Google({
  disabled: true,
});

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

telemetry.disableTracker('google');

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

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

telemetry.enableTracker('google');

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

telemetry.logEvent(); // google 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

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file.