@esri/telemetry-google

Google plugin for 'Telemetry.js' library

Usage no npm install needed!

<script type="module">
  import esriTelemetryGoogle from 'https://cdn.skypack.dev/@esri/telemetry-google';
</script>

README

ArcGIS Telemetry Google

This library exports the telemetry-google plugin for the Telemetry.js package to interact with Google Analytics.

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, and create an instance of the plugin, and pass it as an plugin 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)

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

Server

telemetry-google requires universal-analytics 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 universalAnalyticsTracker = ua('UA-1234567')

const googleTracker = new Google({
  uaTracker:  universalAnalyticsTracker // 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.jswith the telemetry-googleplugin, telemetry data will be sent to the Google Analytics instance of the Google Analytics Tracking ID.

Google Analytics Configuration

  • Follow instructions on getting started with Google Analytics
  • Include the Google Analytics Script in your application. This library DOES NOT bundle Google Analytics trackers, rather it makes calls to trackers that are already on the page.
  • Pass in an object containing the mapping for your custom dimensions and metrics
// or if you are using optional custom dimensions and/or custom metrics
{
  googleOptions: {
    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.

{
  googleOptions: {
    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