Have ideas to improve npm?Join in the discussion! »

    @esri/telemetry

    3.1.0 • Public • Published

    Telemetry.js

    npm version js-standard-style

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

    ** 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 NPMs to your parent project if you require the Amazon tracker.

    API

    Usage

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

    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

    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)

    Errors

    telemetry.logError(error)

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

    How to use

    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.

    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

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

    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

    878

    Version

    3.1.0

    License

    Apache-2.0

    Unpacked Size

    461 kB

    Total Files

    16

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar