@esri/telemetry

    3.2.1 • Public • Published

    ArcGIS-Telemetry.js

    npm version js-standard-style

    ArcGIS Telemetry is a library for tracking usage analytics in web applications and web services. It provides a common interface to various analytics systems. This allows applications to be configured for specific analytics platforms and customer configured tracking keys.

    ArcGIS Telemetry currently supports Amazon Mobile Analytics and Google Analytics. Please add an issue or submit a PR for additional analytics platforms as necessary.

    Why 'Telemetry'?

    This library is referred to as 'Telemetry' instead of 'Analytics' so that it is not confused with geospatial analytics.

    Example API

    telemetry.logPageView()
    telemetry.logEvent({category: 'test', action: 'test', label: 'test'})

    Contents

    How to use

    Install via npm

    npm install -S @esri/telemetry

    ** NOTE **

    • If using version 2.x.x or greater, you are required to have some version of fetch available globally. Most browsers now include, but a polyfill will work.
    • If using version 3.x.x or greater, you are required to add analytics and @analytics/aws-pinpoint modules to your parent project if you require the Amazon tracker.

    Load in Browser

    <script src="dist/Telemetry.js"></script>

    Load for Server Telemetry

    import * as Telemetry from '@esri/telemetry'`

    Using Telemetry.js for Server telemetry

    Telemetry.js uses the universal-analytics module for sending telemetry data from Node environment to Google Analytics.

    Google Analytics

    To use ArcGIS Telemetry within a Node application, instantiate and use Telemetry by providing the required Google Tracking ID.

    const telemetry = Telemetry.load({
      google: {
        trackingId: 'YOUR_GOOGLE_TRACKING_ID' // REQUIRED e.g. UA-000000-2
      }
    })

    Telemetry.load returns a promise

    Additional Google Analytics configuration can be added. Configure Google Analytics Server telemetry allows for sending Events and Errors. Log an event to Google Analytics after instantiating by following telemetry.logEvent(event) and telemetry.logError(error)

    Browser new Telemetry(options)

    To use ArcGIS Telemetry you first need to configure and include the vendor script. Then you can instantiate and use Telemetry.

    const telemetry = new Telemetry ({
      debug: false, // OPTIONAL true || false whether to log each event to the console
      // Trackers to use: "amazon" or "google".  "google" tracker currently needs no options
      amazon: {
        amazon: {
          userPoolID: 'YOUR_USER_POOL_ID', // REQUIRED e.g. us-east-1:aed3c2fe-4d28-431f-abb0-fca6e3167a25
          app: {
            name: 'YOUR_APP_NAME', // REQUIRED e.g. ArcGIS Hub
            id: 'YOUR_APP_ID', // REQUIRED e.g. 36c5713d9d75496789973403b13548fd
            version: 'YOUR_APP_VERSION' // REQUIRED e.g. 1.0
          }
        }
      },
      google: {},
      portal: { // Optional portal/self object
        subscriptionInfo: {
          type: 'In House'
        },
        user: { // OPTIONAL Can be the entire portal/self user object
          username: 'amazing_map_woman',
          orgId: '1ef',
          userSince: 1503924854932,
          lastLogin: 1503924854932
        }
      }
    })

    Configuration

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

    Configure Amazon Analytics

    • 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
    {
      userPoolID: USER_POOL_ID,
      fips: true, // defaults to false
      app: {
        name: APP_NAME,
        id: APP_ID,
        version: APP_VERSION
      }
    }

    Configure Google Analytics

    • 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
    // 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.

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

    {
      google: {
        disabled: true,
        ...
      },
      amazon: {
        disabled: false,
        ...
      }
    }

    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

    API

    Methods

    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.
    • category and action are required when sending telemetry from Node

    E.g.

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

    Errors

    telemetry.logError(error)

    IMPORTANT

    • category and action are required when sending telemetry from Node

    E.g.

    const options = {
      error: 'Service failed count request',
      urlRequested: 'http://featureserver.com/FeatureServer/0/query?f=json&returnCountOnly=true',
      statusCode: 500
    }
    telemetry.logError(options)

    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.

    Workflows are saved in browser local storage when available. They can be retreived from another tab as long as they were started within 30 minutes.

    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'})

    Options

    portal

    Pass the results of a portal/self call e.g. https://www.arcgis.com/sharing/rest/portals/self?f=json into options.portal. This will automatically set the user and organization information of the present user and Telemetry will automatically log these values.

    user

    If you do not have access to portal/self or do not want to make that HTTP call, you can also pass options.user e.g.

    options = {
      user: {
        username: 'amazing_map_woman',
        orgId: '1ef',
        userSince: 1503924854932,
        lastLogin: 1503924854932
      }
    }

    You can also call telemetry.setUser with an object like the one above to set the user after Telemetry has already been initiated.

    debug

    Pass options.debug to view each event in the console. This is useful for development and testing

    Develop

    Install

    yarn install

    Build

    yarn run build

    Test

    yarn test

    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

    Install

    npm i @esri/telemetry

    DownloadsWeekly Downloads

    443

    Version

    3.2.1

    License

    Apache-2.0

    Unpacked Size

    502 kB

    Total Files

    16

    Last publish

    Collaborators

    • katelynseitz
    • jamin415
    • noahmulfinger
    • ssylvia
    • paulcpederson
    • jgravois
    • patrickarlt
    • nixta
    • odoe
    • jwasilgeo
    • tomwayson
    • benstoltz
    • dbouwman
    • thollingshead
    • hhkaos
    • dpaddock
    • esri_dev
    • driskull
    • jpurusho
    • rlibed
    • mtschudi
    • ajturner
    • gavinr
    • pranavkulkarni
    • kellyhutchins
    • mjuniper
    • rsteilberg
    • john4818
    • pr3tori4n
    • gbrown-gis
    • haoliang
    • macandcheese
    • jcfranco
    • alan0002
    • drewctate
    • richgwozdz
    • rweber.esri
    • geemike
    • vivzhang
    • juliannemarik
    • julio8a
    • drspacemanphd
    • cpgruber
    • cpalazzoloesri