@esri/telemetry-adobe

This library exports the telemetry-adobe plugin for the Telemetry.js package to interact with Adobe Analytics.

Table of Contents

• @esri/telemetry-adobe
  • Table of Contents
  • Installation
  • How to Use
• AdobeAnalytics
  • eVar and Prop in Adobe Analytics:
    • Default Mappings
    • logPageView() Example:
    • eventLog() Example:
• AdobeAlloy
• Adobe Analytics Configuration
  • Issues
  • Contributing
  • License

Installation

npm install @esri/telemetry
npm install @esri/telemetry-adobe

How to Use

@esri/telemetry-adobe package works in the client-side browser (note: there is no support for server-side Node.js).

To use, install the package, include it in your project, and create an instance of the plugin, and pass it as a plugin with @esri/telemetry

Below are is an example of how to use the Adobe plugin.

Adobe Analytics

JS

import { Telemetry } from '@esri/telemetry';
import { AdobeAnalytics } from '@esri/telemetry-adobe';

const adobeAnalyticsTracker = new AdobeAnalytics({
  /****** reportSuite ******
   * This is the id for the Report Suite where your telemetry data will be logged to
   */
  reportSuite: 'myreportsuite',

  /****** trackingServer ******
   * This is the Tracking Server url, you can get it from your adobe account
   */
  trackingServer: 'myServer.com',

    /****** trackingServerSSL ******
   * This is the Secure Tracking Server url, you can get it from your adobe account
   */
  trackingServerSSL: 'mySecureServer.com',

  /***** dimensions *******
   * Mapping for dimensions to the eVars (and possibly props) they will get stored as.
   * Note: if you are mapping props, then you have to explicitly remap ALL predefined props,
   * or else class will error out on instantiation.
   *
   * ex:
   *  dimensions: {
   *    customValue: "eVar1",
   *    anotherCustom: "eVar2"
   *  }
   *
   * becomes the following when sent to the server:
   *
   * {
   *   eVar1: {actual value for "customValue"},
   *   eVar2: {actual value for "anotherCustom"}
   * }
   */
  dimensions: {
    customValue: 'eVar1',
    anotherCustom: 'eVar2',
  },
});

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

const telemetry = new Telemetry(telemetryOptions);
await telemetry.init();
telemetry.logPageView();
telemetry.logEvent({
  category: 'Dataset',
  action: 'Attribute Inspect',
  label: 'Metadata',
  attribute: 'Metadata',
  details: 'Metadata',
  customValue: 'val',
  anotherCustom: 12,
});

eVar and Prop in Adobe Analytics:

Default Mappings

Adobe Analytics uses variables called eVars and props for storing custom values (eVar/prop). Our plugin automatically allocates values to a certain set of props. Here are the default Mappings that are used:

prop1: eventType;
prop2: referrer;
prop3: hostname;
prop4: path;
prop5: pageName;
prop6: previousPageName;
prop7: previousPageUrl;
prop8: category;
prop9: action;
prop10: label;
prop11: attribute;
prop12: details;

You can use the dimensions parameter to specify how values are mapped to eVars and also to possibly remap the prop mappings specified above. NOTE: IF YOU REMAP 1 PROP ABOVE, THEN YOU MUST EXPLICITLY DEFINE THE MAPPING FOR ALL 12 OF THEM. Here's an example:

const adobeAnalyticsTracker = new AdobeAnalytics({
  reportSuite: 'myreportsuite',
  trackingServer: 'myServer.com',
  trackingServerSSL: 'mySecureServer.com',
  dimensions: {
    extra1: 'eVar1',
    details: 'prop1',
    attribute: 'prop2',
    label: 'prop3',
    action: 'prop4',
    category: 'prop5',
    previousPageUrl: 'prop6',
    previousPageName: 'prop7',
    referrer: 'prop8',
    path: 'prop9',
    pageName: 'prop10',
    hostname: 'prop11',
    eventType: 'prop12',
  },
});

logPageView() Example:

const adobeAnalyticsTracker = new AdobeAnalytics({
  reportSuite: 'myreportsuite',
  trackingServer: 'myServer.com',
  trackingServerSSL: 'mySecureServer.com',
   dimensions: {
     customValue: "eVar1",
     anotherCustom: "eVar2"
  }
})

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

const telemetry = new Telemetry(telemetryOptions);
await telemetry.init();

telemetry.logPageView("adobe.html", {
  customValue: "My Extra Data 1",
  anotherCustom: "My Extra Data 2"
})

    Results in =>

      prop1: "pageView"           // eventType
      prop2:  [hostname]          // hostname
      prop3:  [pageName]          // pageName
      prop4:  [path]              // path
      prop5:  [referrer]          // referrer
      prop6:  [previousPageName]  // previousPageName
      prop7:  [previousPageUrl]   // previousPageUrl
      prop8:  undefined           // category
      prop9:  undefined           // action
      prop10: undefined           // label
      prop11: undefined           // attribute
      prop12: undefined           // details
      eVar1: "My Extra Data 1"    // customValue
      eVar2: "My Extra Data 2"    // anotherCustom

eventLog() Example:

const adobeAnalyticsTracker = new AdobeAnalytics({
  reportSuite: 'myreportsuite',
  trackingServer: 'myServer.com',
  trackingServerSSL: 'mySecureServer.com',
   dimensions: {
    randomProp1: "eVar1",
    randomProp2: "eVar2",
    randomProp3: "eVar3"
  }
})

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

const telemetry = new Telemetry(telemetryOptions)
await telemetry.init();

telemetry.logEvent({
  category: "myCategory",
  attribute: "myAttribute",
  randomProp1: "val",
  randomProp2: "val2",
  randomProp3: 72
});

Results in =>

  prop1: "other"              // eventType
  prop2:  [hostname]          // hostname
  prop3:  [pageName]          // pageName
  prop4:  [path]              // path
  prop5:  [referrer]          // referrer
  prop6:  [previousPageName]  // previousPageName
  prop7:  [previousPageUrl]   // previousPageUrl
  prop8:  "myCategory"        // category
  prop9:  undefined           // action
  prop10: undefined           // label
  prop11: "myAttribute"       // attribute
  prop12: undefined           // details
  eVar1: "val"                // randomProp1
  eVar2: "val2"               // randomProp2
  eVar3: 72                   // randomProp3

Adobe Analytics Configuration

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.

{
  adobeOptions: {
    disabled: true,
    ...
  }
}

Post initialization, it is possible to disable & enable specific trackers using disableTracker and enableTracker methods.

telemetry.disableTracker('adobe-analytics');
telemetry.logPageView(); // no AdobeAnalytics page view logged
telemetry.logEvent(); // no AdobeAnalytics event logged
telemetry.enableTracker('adobe-analytics');
telemetry.logPageView(); // AdobeAnalytics page view logged
telemetry.logEvent(); // AdobeAnalytics event logged

telemetry.disableTracker('adobe-alloy');
telemetry.logPageView(); // no AdobeAlloy page view logged
telemetry.logEvent(); // no AdobeAlloy event logged
telemetry.enableTracker('adobe-alloy');
telemetry.logPageView(); // AdobeAlloy page view logged
telemetry.logEvent(); // AdobeAlloy event logged

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.