@esri/telemetry

This is the "core" package for ArcGIS-Telemetry.js. It is necessary for sending data to analytics platforms such as Google, Adobe, and AWS.

Table of Contents

• @esri/telemetry
  • Table of Contents
  • Installation
  • Usage
  • Issues
  • Contributing
  • License

Installation

npm install @esri/telemetry

Usage

Terminology

• Telemetry: the vendor-agnostic collection and routing interface for usage signals.
• Plugin: the external-facing integration term used in documentation and in the plugins configuration array.
• Tracker: the internal code-level actor/interface used by the core runtime.
• Analytics: downstream destination/reporting systems (for example AWS, Google, Adobe, Siteimprove).

Privacy Tracking Consent

Starting with version 7.x, telemetry.js has support for privacy tracking consent. The host application can decide to enable this behavior passing .requireConsent in the options passed into the constructor, along with an optional IPrivacySettings object. The example below shows this structure.

Users can consent to the following types of "tracking":

• Performance: Allows only application performance information to be sent and stored
• Functional: Allows for functional information to be stored, like perferences, past searches etc
• Targeting: Allows for user targeting information to be sent

When requireConsent is passed, and no userPrivacySettings is sent, telemetry.js operates as though the user has opted out of all tracking. This is expected behavior as per GDPR.

When userPrivacySettings.performance: true, and an Amazon plugin is configured, it will be initialized.

For Hub Sites (and some other platform applications) customers can configure additional 3rd party tracking systems (Google Analytics, Adobe, SiteImprove). In order for those trackers to be enabled, the end-user must opt into performance, functional and targeting, because we do not know or control what the 3rd party trackers are doing, so we must assume they are tracking all three.

In Browser

import { Telemetry } from '@esri/telemetry';

// create options object
const opts = {
  requireConsent: true, // if your app requires privacy consent, set this to true
  plugins: [list of vendor plugins goes in here]
};
// Host app should load user privacy settings from localStorage or cookies
const storedSettings = window.localStorage.getItem('esri_privacy_settings');
if (storedSettings) {
  opts.userPrivacySettings = JSON.parse(storedSettings);
} else {
  // this is optional, as telemetry.js will construct the same thing
  // if requiteConsent: true and not settings are passed in
  opts.userPrivacySettings = {
    id: '3ef...', // create some unique id
    timestamp: Date.now(),
    accepted: false, // user has not actually set these, so this is false
    performance: false, // all set to false by default
    functional: false,
    targeting: false,
  }
}
// create the telemetry instance
const telemetry = new Telemetry(opts);

await telemetry.init();
// now it is ready to go

In Server

Since this is done on the server, it is not able to take user privacy settings into account. Thus, it is discouraged to inject script tags on the server, as tracking is likely to start before the host application actually boots and can apply the user privacy settings.

import { Telemetry } from '@esri/telemetry';

// create options object
const opts = {
  plugins: [list of vendor plugins goes in here]
};
// create the telemetry instance
const telemetry = new Telemetry(opts);
// in server
const scriptTags = telemetry.getScriptTags();
// now inject script tags into html page before sending it down

Issues

If something isn't working, please take a look at previously logged issues first. Have you found a new bug? Create an issue here.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

License

Copyright © 2022 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file.