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
})
and eVarProp
in Adobe Launch:
Default Mappings
Adobe Launch uses variables called eVar
s and prop
s for storing custom values (eVar/prop). Our plugin automatically allocates values to a certain set of prop
s. 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