@esri/telemetry - npm Package Compare versions

Comparing version 3.1.1 to 3.2.0

CHANGELOG.md

@@ -7,2 +7,6 @@ # Change Log
 
+## [3.2.0] - 09/13/2021 
+### Added
+* Add node support for google analytics [Hub 1889](https://devtopia.esri.com/dc/hub/issues/1889)
+
 ## [3.1.1] - 06/07/2021
@@ -145,8 +149,9 @@ ### Fixed
 
-[3.1.1]: https://github.com/arcgis/telemetry.js/compare/v3.1.0...v3.1.1
-[3.1.0]: https://github.com/arcgis/telemetry.js/compare/v3.0.2...v3.1.0
-[3.0.2]: https://github.com/arcgis/telemetry.js/compare/v3.0.1...v3.0.2
-[3.0.1]: https://github.com/arcgis/telemetry.js/compare/v3.0.0...v3.0.1
-[3.0.0]: https://github.com/arcgis/telemetry.js/compare/v2.0.0...v3.0.0
-[2.0.0]: https://github.com/arcgis/telemetry.js/compare/v1.5.0...v2.0.0
+[3.2.0]: https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/compare/v3.1.1...v3.2.0
+[3.1.1]: https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/compare/v3.1.0...v3.1.1
+[3.1.0]: https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/compare/v3.0.2...v3.1.0
+[3.0.2]: https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/compare/v3.0.1...v3.0.2
+[3.0.1]: https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/compare/v3.0.0...v3.0.1
+[3.0.0]: https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/compare/v2.0.0...v3.0.0
+[2.0.0]: https://devtopia.esri.com/WebGIS/arcgis-telemetry.js/compare/v1.5.0...v2.0.0
 [1.5.0]: https://github.com/arcgis/telemetry.js/compare/v1.4.0...v1.5.0
@@ -153,0 +158,0 @@ [1.4.0]: https://github.com/arcgis/telemetry.js/compare/v1.3.6...v1.4.0

package.json

 {
   "name": "@esri/telemetry",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "A JavaScript Implementation of the ArcGIS Telemetry Specification",
@@ -32,2 +32,6 @@ "main": "dist/telemetry.js",
       "name": "Daniel Fenton"
+    },
+    {
+      "name": "Bob Vo",
+      "email": "[e-mail]"
     }
@@ -40,3 +44,2 @@ ],
   "homepage": "https://github.com/ArcGIS/telemetry.js#readme",
-  "dependencies": {},
   "devDependencies": {
@@ -46,2 +49,3 @@ "@analytics/aws-pinpoint": "^0.4.3",
     "babel-cli": "^6.24.1",
+    "babel-plugin-dynamic-import-node": "^2.3.3",
     "babel-plugin-external-helpers": "^6.22.0",
@@ -75,2 +79,5 @@ "babel-plugin-transform-es2015-destructuring": "^6.23.0",
   },
+  "optionalDependencies": {
+    "universal-analytics": "^0.4.23"
+  },
   "standard": {
@@ -77,0 +84,0 @@ "globals": [

README.md

@@ -1,2 +0,2 @@
-# Telemetry.js
+# ArcGIS-Telemetry.js
 
@@ -6,13 +6,100 @@ [![npm version][npm-img]][npm-url]
 
-This is a vanilla JavaScript implementation of the new ArcGIS telemetry specification. It currently supports Amazon Mobile Analytics and Google Analytics
+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](https://desktop.arcgis.com/en/analytics/).
+
+## Example API
+
+```js
+telemetry.logPageView()
+telemetry.logEvent({category: 'test', action: 'test', label: 'test'})
+```
+
+# Contents
+
+- [ArcGIS-Telemetry.js](#arcgis-telemetryjs)
+  * [Why 'Telemetry'?](#why--telemetry--)
+  * [Example API](#example-api)
+- [How to use](#how-to-use)
+  * [Install via npm](#install-via-npm)
+  * [Load in Browser](#load-in-browser)
+  * [`new Telemetry(options)`](#-new-telemetry-options--)
+- [Configuration](#configuration)
+  * [Configure Amazon Analytics](#configure-amazon-analytics)
+  * [Configure Google Analytics](#configure-google-analytics)
+- [API](#api)
+  * [Methods](#methods)
+    + [`telemetry.logPageView(page)`](#-telemetrylogpageview-page--)
+    + [`telemetry.logEvent(event)`](#-telemetrylogevent-event--)
+  * [Errors](#errors)
+    + [`telemetry.logError(error)`](#-telemetrylogerror-error--)
+  * [Workflows](#workflows)
+    + [`telemetry.startWorkflow(name, [attributes])`](#-telemetrystartworkflow-name---attributes---)
+    + [`telemetry.stepWorkflow(name, step, [attributes])`](#-telemetrystepworkflow-name--step---attributes---)
+    + [`telemetry.cancelWorkflow(name, [attributes])`](#-telemetrycancelworkflow-name---attributes---)
+    + [`telemetry.endWorkflow(name, [attributes])`](#-telemetryendworkflow-name---attributes---)
+  * [Options](#options)
+    + [portal](#portal)
+    + [user](#user)
+    + [debug](#debug)
+- [Develop](#develop)
+  * [Install](#install)
+  * [Build](#build)
+  * [Test](#test)
+  * [Roadmap](#roadmap)
+
+
+
+# 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` NPMs to your parent project if you require the Amazon tracker.
+* 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.
 
-# API
+## Load in Browser
 
-## Usage
+```html
+<script src="dist/Telemetry.js"></script>
+```
 
+## Load for Server Telemetry
+
 ```js
+import * as Telemetry from '@esri/telemetry'`
+```
+
+## Using Telemetry.js for Server telemetry
+
+Telemetry.js uses the [universal-analytics](https://github.com/peaksandpies/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.
+
+```js
+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](#configure-google-analytics)
+Server telemetry allows for sending Events and Errors. Log an event to Google Analytics after instantiating by following [`telemetry.logEvent(event)`](#-telemetrylogevent-event--) and [`telemetry.logError(error)`](#-telemetrylogerror-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. 
+
+```js
 const telemetry = new Telemetry ({
@@ -46,20 +133,47 @@ debug: false, // OPTIONAL true || false whether to log each event to the console
 
-### Options
+# Configuration
 
-#### portal
+- Debug mode: If `debug` is set to `true` events and page views will be logged to the console
 
-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.
+## Configure Amazon Analytics
 
-#### user
+  - 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 do not have access to `portal/self` or do not want to make that HTTP call, you can also pass `options.user` e.g.
+ ```js
+ {
+   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](https://support.google.com/analytics/answer/1008015?hl=en&ref_topic=3544906)
+  - 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](https://support.google.com/analytics/answer/2709828?hl=en)
 ```js
-options = {
-  user: {
-    username: 'amazing_map_woman',
-    orgId: '1ef',
-    userSince: 1503924854932,
-    lastLogin: 1503924854932
+// 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
+    }
   }
@@ -69,12 +183,34 @@ }
 
-You can also call `telemetry.setUser` with an object like the one above to set the user after `Telemetry` has already been initiated.
+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.
 
-#### debug
+Additionally, you can disable individual trackers when initializing the `Telemetry` object by passing `disabled: true` in the tracker options.
 
-Pass `options.debug` to view each event in the console. This is useful for development and testing
+```js
+{
+  google: {
+    disabled: true,
+    ...
+  },
+  amazon: {
+    disabled: false,
+    ...
+  }
+}
+```
 
+Post initialization, it is possible to disable & enable specific trackers using `disableTracker` and `enableTracker` methods.
 
+```js
+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
+```
 
-## Direct tracking
+# API
 
+## Methods
+
 ### `telemetry.logPageView(page)`
@@ -92,4 +228,7 @@
 
-**IMPORTANT** Do not pass a username except as `event.user`. Otherwise it will not be anonymized.
+**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.
@@ -113,2 +252,5 @@
 
+**IMPORTANT** 
+ - `category` and `action` are required when sending telemetry from Node
+
 E.g.
@@ -163,83 +305,21 @@
 
-## How to use
 
-### Via npm
+## Options
 
-`npm install -S @esri/telemetry`
+### portal
 
-** 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.
+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.
 
-### In the browser
-```js
-<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
+### user
 
-- Debug mode: If `debug` is set to `true` events and page views will be logged to the console
+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.
 
-- 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
-
- ```js
- {
-   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](https://support.google.com/analytics/answer/1008015?hl=en&ref_topic=3544906)
-  - 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](https://support.google.com/analytics/answer/2709828?hl=en)
 ```js
-// 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
-    }
+options = {
+  user: {
+    username: 'amazing_map_woman',
+    orgId: '1ef',
+    userSince: 1503924854932,
+    lastLogin: 1503924854932
   }
@@ -249,34 +329,13 @@ }
 
-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.
+You can also call `telemetry.setUser` with an object like the one above to set the user after `Telemetry` has already been initiated.
 
-Additionally, you can disable individual trackers when initializing the `Telemetry` object by passing `disabled: true` in the tracker options.
+### debug
 
-```js
-{
-  google: {
-    disabled: true,
-    ...
-  },
-  amazon: {
-    disabled: false,
-    ...
-  }
-}
-```
+Pass `options.debug` to view each event in the console. This is useful for development and testing
 
-Post initialization, it is possible to disable & enable specific trackers using `disableTracker` and `enableTracker` methods.
 
-```js
-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
 
-## Develop
+## Install
 
-### Install
-
 ```bash
@@ -283,0 +342,0 @@ yarn install

New alerts

Empty package

Supply chain risk

Package does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Found 1 instance in 1 package

Improved metrics

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

363

increased by19.41%

Number of medium supply chain risk alerts

2

decreased by-83.33%

Worsened metrics

Total package byte prevSize

19613

decreased by-95.74%

Dependency count

3

increased by50%

Dev dependency count

27

increased by3.85%

Number of package files

4

decreased by-75%

Lines of code

0

decreased by-100%

No dependency changes