@esri/telemetry-amazon

Amazon plugin for 'Telemetry.js' library

Usage no npm install needed!

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

README

ArcGIS Telemetry Amazon

This library exports the telemetry-amazon plugin for the Telemetry.js package to interact with AWS Analytics store. This package uses the analytics and @analytics/aws-pinpoint packages.

Installation

npm install @esri/telemetry
npm install @esri/telemetry-amazon

How to Use

@esri/telemetry-amazon packages works in the client-side browser and (WIP 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 telemetry-amazon plugin.

import Telemetry from '@esri/telemetry'
import Amazon from '@esri/telemetry-amazon'

const amazonTracker = new Amazon({
  userPoolID: USER_POOL_ID,
  fips: true, // defaults to false
  app: {
    name: APP_NAME,
    id: APP_ID,
    version: APP_VERSION,
  },
})

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

const telemetry = new Telemetry(telemetryOptions)

telemetry.logPageView()
telemetry.logEvent()

After initializing Telemetry.jswith the telemetry-amazonplugin, telemetry data will be sent to the AWS Pinpoint instance of the provided App.

Amazon Analytics Configuration

  • Get your app and user pool ID from AWS Pinpoint instance
  • Pass in options for amazon when initiating the Telemetry object
  • the fips option determines if AWS FIPS endpoints are used for cognito and pinpoint requests

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.

{
  amazonOptions: {
    disabled: true,
    ...
  }
}

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

telemetry.disableTracker('amazon')
telemetry.logPageView() // no amazon page view logged
telemetry.logEvent() // no amazon event logged
telemetry.enableTracker('amazon')
telemetry.logPageView() // amazon page view logged
telemetry.logEvent() // amazon event logged

Example

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)