@esri/telemetry-amazon

This is a plugin for the Telemetry.js package to interact with an AWS Analytics store.

Table of Contents

• @esri/telemetry-amazon
  • Amazon Pinpoint Retirement & Migration
  • How to Use
  • Amazon Configuration
  • Example
    • telemetry.logEvent(event)
  • Telemetry Sharing Permissions
    • Portal Items
    • Usage
  • Issues
  • Contributing
  • License

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

Amazon Pinpoint Retirement & Migration

Amazon Pinpoint will be retired on October 30, 2026. After this date, Pinpoint can no longer be used for telemetry delivery. See the official AWS retirement announcement for details.

By default, the Amazon tracker now sends events to Esri's backend instead of Pinpoint. Once on a compatible version of the @esri/telemetry-amazon library (^6.0.0), update your configuration to point to the environment matching your app's id:

const amazonTracker = new Amazon({
  env: 'production' | 'qa' | 'dev',
  ....
});

All other configuration remains the same.

NOTE: After October 30, 2026 the mode: 'pinpoint' property will be a no-op, and all traffic will be routed through the Esri backend.

How to Use

@esri/telemetry-amazon package works in the client-side browser and server-side Node.js. To use it, install the package, include it in your project, create an instance of the Amazon plugin, and add it to the plugins array 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,
  env: 'production' | 'qa' | 'dev',
  fips: true, // defaults to false
  app: {
    name: APP_NAME,
    id: APP_ID,
    version: APP_VERSION,
  },
  mode: 'pinpoint', // Pinpoint retires on October 30, 2026. Use 'esri' or omit this field for continued support.
});

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

const telemetry = new Telemetry(telemetryOptions);

telemetry.logPageView();

telemetry.logEvent();

After initializing Telemetry.js with the Amazon plugin, telemetry data will be sent to the configured destination.

Error handling

Temporary network failures (500, 503) and HTTP 408, 429, and ThrottlingException 400 responses are retried with exponential backoff; other 4xx responses are treated as permanent failures. Retry-After is honored in place of the library's backoff timeouts for 429 and 503 responses.

Backend payload limits

The backend imposes the following limits:

• Individual attributes in an event payload are capped at 500 characters. Attributes longer than this are truncated to the first 500 characters.

• Events received in quick succession are queued to be sent in batches. The batch will be submitted to the server when any of the following conditions are met:

  • More than 500 events have been queued at once
  • The total size of the payload exceeds 3mb
    • If a single event exceeds this size, the payload will be dropped. This is unlikely, but an event with many attributes at the character limit can reach several mb
  • 5 seconds have elapsed since the last event was captured
  • The user navigates away from the page

Amazon Configuration

• Get your app and user pool ID from AWS
• Pass in an options object to create an instance of the Amazon plugin
• the fips option determines if AWS FIPS endpoints are used for cognito requests
• The env option designates which Esri endpoint events will be set to, and defaults to "dev"
  • In a future release this env will be auto-detected, but this parameter will remain as a manual override
• Pass in an object containing the mapping for your custom dimensions and metrics

// or if you are using optional custom dimensions and/or custom metrics
const amazonTracker = new Amazon({
  dimensions: {
    datasetID: 1,
    attribute: 2,
    serviceQuery: 3,
  },
  metrics: {
    duration: 1,
    size: 2,
  },
});

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.

const amazonTracker = new Amazon({
  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);

Telemetry Sharing Permissions

Portal Items

telemetry-amazon contains static methods for setting and getting telemetry access for portal items.

Usage

import { Amazon } from '@esri/telemetry-amazon'
...

// see https://developers.arcgis.com/arcgis-rest-js/api-reference/arcgis-rest-request/ArcGISIdentityManager/
const authentication = await ArcGISIdentityManager.signIn(username, password)

const getAccessParams = {
  id: '1ef',
  authentication,
}

const access = await Amazon.getAccessPermissions(getAccessParams: IGetAccessPermissionsParams)

const setAccessParams = {
  id: '1ef',
  authentication,
  username: 'dev_pre_a_hub_admin',
  accessChangeset: [
    {
      action: 'add',
      targetProperty: 'public',
    }
  ]
}

const result = await Amazon.setAccessPermissions(setAccessParams: ISetAccessPermissionsParams)

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 © 2026 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.