@esri/telemetry

Telemetry.js

This is a vanilla JavaScript implementation of the new ArcGIS telemetry specification. It currently supports Amazon Mobile Analytics and Google Analytics

API

Direct tracking

telemetry.logPageView(page)

The page variable is optional. If it is not passed in, the library will use window.location

E.g.

telemetry.logPageView('/datasets/1ef')

telemetry.logEvent(event)

IMPORTANT Do not pass a username except as event.user. Otherwise it will not be anonymized.

E.g.

const event = {
  category: 'Dataset',
  action: 'Attribute Inspect',
  label: 'Crimes 2016',
  datasetID: '1ef',
  attribute: 'crime_type',
  user: 'amazing_map_woman'
}

telemetry.logEvent(event)

Workflows

Workflows are meant to track a logical group of actions by a user from start to finish.

First a workflow is created with startWorkflow. Then steps are added with stepWorkflow. Finally a workflow is either canceled with cancelWorkflow or completed successfully with endWorkflow.

Workflows are tracked internally by name so this value must not change through the life of a workflow in order for steps and duration to be tracked properly.

telemetry.startWorkflow(name, [attributes])

telemetry.startWorkflow('add layer')
telemetry.startWorkflow('add layer', {details: 'from search'})

telemetry.stepWorkflow(name, step, [attributes])

telemetry.stepWorkflow('add layer', 'search', {details: 'street trees'})

telemetry.cancelWorkflow(name, [attributes])

telemetry.cancelWorkflow('add layer')
telemetry.cancelWorkflow('search', {details: 'back to home'})

telemetry.endWorkflow(name, [attributes])

telemetry.endWorkflow('add layer')
telemetry.endWorkflow('add layer', {details: 'pasadena street trees'})

How to use

Via npm

npm install -S @esri/telemetry

In the browser

<script src="dist/Telemetry.js"></script>
<script>
const telemetry = new Telemetry({
  amazon: {
    userPoolID: 'us-east-1:aed3c2fe-4d28-431f-abb0-fca6e3167a25',
    app: {
      name: 'test',
      id: '36c5713d9d75496789973403b13548fd',
      version: '1.0'
    }
  },
  google: {
    dimensions: {
      datasetId: 6,
      attribute: 7,
      serviceQuery: 8,
      searchQuery: 9,
      objectId: 10,
      facetValue: 11
    }
  }
})
telemetry.logPageView()
telemetry.logEvent({category: 'test', action: 'test', label: 'test'})
</script>

Configuration

• Debug mode: If debug is set to true events and page views will be logged to the console

• Amazon

  • Request your app and user pool ID from (TBD)
  • Pass in options for amazon when initiating the Telemetry object

{
  userPoolID: USER_POOL_ID,
  app: {
    name: APP_NAME,
    id: APP_ID,
    version: APP_VERSION
  }
}

• Google
  • 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 google: true or an object containing the mapping for your custom dimensions and metrics
    • Read here about custom dimensions and metrics

// if you are using no custom dimensions or metrics
{
  google: true
}
// or if you are using optional custom dimensions and/or custom metrics
{
  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 intializing the Telemetry object. Then you can continue to call the methods on your instance of Telemetry without throwing exceptions or logging errors.

Build

• npm install
• npm run compile

Roadmap

1. Support Processes
   • E.g. time and track the process of geocoding 100 addresses
2. Send events in batches
   • Use fewer HTTP calls and improve performance by sending near-simultaneous events in groups