@esri/telemetry-amazon

This is a plugin for the Telemetry.js package to interact with an AWS Analytics store. This package uses the third-party libraries, analytics and @analytics/aws-pinpoint packages.

Table of Contents

• @esri/telemetry-amazon
  • Table of Contents
  • 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

How to Use

@esri/telemetry-amazon packages works in the client-side browser and server-side Node.js. To use, install the package, include it in your project, create an instance of the 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,
  fips: true, // defaults to false
  app: {
    name: APP_NAME,
    id: APP_ID,
    version: APP_VERSION,
  },
});

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

const telemetry = new Telemetry(telemetryOptions);

telemetry.logPageView();

telemetry.logEvent();

After initializing Telemetry.js with the telemetry-amazon plugin, telemetry data will be sent to the AWS Pinpoint instance of the provided App.

Amazon Configuration

• Get your app and user pool ID from AWS Pinpoint instance
• Pass in options object to create an instance of the plugin
• the fips option determines if AWS FIPS endpoints are used for cognito and pinpoint requests
• 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 googleTracker = 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'
...

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

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

const setAccessParams = {
  id: '1ef',
  authentication: PortalUserSession,
  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 © 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.