@esri/telemetry-adobe
This library exports the telemetry-adobe plugin for the Telemetry.js package to interact with Adobe Analytics.
Table of Contents
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
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.