@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

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)

How to use

Include in your app

<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

• 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 Workflows.
   • E.g. tracking the flow of finding and adding a layer to a webmap
2. Support Processes
   • E.g. time and track the process of geocoding 100 addresses
3. Send events in batches
   • Use fewer HTTP calls and improve performance by sending near-simultaneous events in groups