@esri/telemetry-adobe

Adobe plugin for 'Telemetry.js' library

Usage no npm install needed!

<script type="module">
  import esriTelemetryAdobe from 'https://cdn.skypack.dev/@esri/telemetry-adobe';
</script>

README

ArcGIS Telemetry Adobe

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

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).

There are 2 classes available from this Plugin. AdobeLaunch allows you to configure your Adobe Launch based telemetry Tracker. AdobeAlloy allows you to configure your Adobe Experience Platform Tracker (which is based on the Platform Web SDK). Alloy is the newer utility that Adobe is currently developing on, whereas Launch has been around for a while.

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

Below are two examples of how to use the Adobe plugins.

AdobeLaunch

IMPORTANT: you must put the following into the head tag of your page for Adobe Launch to work properly. You can get this url from your Adobe account.

HTML

<script src="https://assets.adobedtm.com/xyz1234abc/xyz1234abc/launch-xyz1234abc.min.js" async></script>

JS

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

const adobeLaunchTracker = new AdobeLaunch({
  /****** reportSuiteId ******
  * This is the id for the Report Suite where your telemetry data will be logged to  
  */
      reportSuiteId: "myreportsuiteid",

  /***** 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: [adobeLaunchTracker],
  portal: {
    subscriptionInfo: {},
    user: {},
  },
}

const telemetry = new Telemetry(telemetryOptions)

telemetry.logPageView()
telemetry.logEvent({
  category: 'Dataset',
  action: 'Attribute Inspect',
  label: 'Metadata',
  attribute: 'Metadata',
  details: 'Metadata',
  customValue: "val",
  anotherCustom: 12
})

eVar and Prop in Adobe Launch:


Default Mappings


Adobe Launch 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 adobeLaunchTracker = new AdobeLaunch({
    reportSuiteId: "myreportsuiteid",
    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 adobeLaunchTracker = new AdobeLaunch({
   reportSuiteId: "myreportsuiteid",
   dimensions: {
     customValue: "eVar1",
     anotherCustom: "eVar2"
  }
})

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

const telemetry = new Telemetry(telemetryOptions)

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 adobeLaunchTracker = new AdobeLaunch({
   reportSuiteId: "myreportsuiteid",
   dimensions: {
    randomProp1: "eVar1", 
    randomProp2: "eVar2",
    randomProp3: "eVar3"
  }
})

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

const telemetry = new Telemetry(telemetryOptions)

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

AdobeAlloy

IMPORTANT: you must put the following into the head tag of your page for Adobe Alloy to work properly (Option 2 on this page is the only supported option for loading Alloy resources)

HTML

<script>
  !function(n,o){o.forEach(function(o){n[o]||((n.__alloyNS=n.__alloyNS||
  []).push(o),n[o]=function(){var u=arguments;return new Promise(
  function(i,l){n[o].q.push([i,l,u])})},n[o].q=[])})}
  (window,["alloy"]);
</script>
<script src="https://cdn1.adoberesources.net/alloy/2.6.4/alloy.min.js" async></script>

JS

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

const adobeAlloyTracker = new AdobeAlloy({
  /****** edgeConfigId ******
   https://experienceleague.adobe.com/docs/experience-platform/edge/fundamentals/configuring-the-sdk.html?lang=en
  */
    edgeConfigId: "0785328j-hg67-3629-a628-9403jf0k34:dev",
  /****** orgId ******
    https://experienceleague.adobe.com/docs/experience-platform/edge/fundamentals/configuring-the-sdk.html?lang=en
  */
    orgId: "4930FDGSHJKNDGFS920E750CKVK@AdobeOrg"
})

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

const telemetry = new Telemetry(telemetryOptions)

telemetry.logPageView()
telemetry.logEvent({
  category: 'Dataset',
  action: 'Attribute Inspect',
  label: 'Metadata',
  attribute: 'Metadata',
  details: 'Metadata'
})

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-launch')
telemetry.logPageView() // no AdobeLaunch page view logged
telemetry.logEvent() // no AdobeLaunch event logged
telemetry.enableTracker('adobe-launch')
telemetry.logPageView() // AdobeLaunch page view logged
telemetry.logEvent() // AdobeLaunch 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