AA via AEP Web SDK
With this extension you can leverage the benefits of AEP for your Adobe Analytics implementation, without having to learn anything about AEP (e.g., XDM configuration, Datastreams, etc...).
For those wishing to populate Adobe Analytics using the AEP Web SDK, this extension provides the familiar 'Set Variables', 'Send Beacon', and 'Clear Variables' actions of the Adobe Analytics extension. It also provides the 'Set Product String' action of the AA Product String Builder extension. Using this extension as a companion to the Adobe Experience Platform Web SDK extension (AEP Web SDK), you will be able to retire the Adobe Analytics extension (AppMeasurement.js), the Experience Could ID Service (Visitor.js), and the Adobe Target extension (at.js).
The biggest difference when using this extension with the AEP Web SDK for Adobe Analytics data collection is that instead of sending traditional beacons directly to the Adobe Analytics Collection servers (by calling the s.t() or s.tl() functions of AppMeasurment.js), with this extension, you will be sending XDM data to the Adobe Experience Platform's Edge Network (by calling invoking the 'sendEvent' function of the alloy.js library). Once this XDM data gets to Adobe Edge, it is transformed into Adobe Analytics beacons and forwarded to the appropriate Adobe Analytics Collection servers. The XDM to AA mappings that are used by this extension are detailed here.
This extension works in conjunction with the Adobe Experience Platform Web SDK extension. There are two optional configurations for this extension.
This configuration section allows you to specify eVars, props, events, and other variables that are to be included on EVERY beacon that is sent. Note that this is a departure from the functionality of the Adobe Analytics extension where global variable settings are applied to the 's' object once when the extension initializes but not again with each beacon (as was apparently the intention). With this extension, the global settings are applied just before each beacon is sent (and just before any doPlugins function is run, meaning that doPlugins can overwrite the values of variables set in rules or set by the global variables configuration).
CONFIGURE TRACKER USING CUSTOM CODE
In order to make the migration from the Adobe Analytics extension to this extension as straight-forward as possible, the ability to configure the tracker using custom code is supported (to the extent possible). Custom code may be entered in this editor in much the same way as it has traditionally been done when using the Adobe Analytics extension.
Custom configuration code is executed when the extension is initialized at runtime (when the Launch library is loaded into the page and initialized). This custom code provides the 's' object so that you may reference tracking variables directly. The variables that you may access (set or evaluate) are listed below:
- s.eVar1 - s.eVar250 (be careful not to use eVars that your contract doesn't support)
- s.prop1 = s.prop75
- s.hier1 - s.hier5
- s.events via three helper functions:
- s.setEvent(eventName, eventValue, eventId) eventValue and eventId are optional
- s.getEvent(eventName) Returns the value of a given event.
- s.removeEvent(eventName) Removes an event if is it set.
The only configuration variables that are presently supported are s.usePlugins and s.doPlugins. These configuration variables function as you have come to expect; when s.usePlugins is set to true, the function provided by s.doPlugins will be executed as part of the Send Beacon action, as the last step of processing (just before alloy's sendEvent method is executed). For the most part, you can define AA plugins as described here but be advised that some of these plugins rely on the internals of the AppMeasurement.js library and thus, will certainly not work here. If you are in need of plug-in functions, you should probably consider using the Common Web SDK Plugins extension instead of hard-coding them here.
Note that the following configurations and variables are no longer applicable and thus not supported by this extension. If you have a legitimate need for one of these, contact [email protected] to plead your case.
- s.products (Use the 'Set Product String' action for this).
Action Types available with this extension include:
Set Variables - Provides a familiar user interface for setting Adobe Analytics variables. When paired with a ‘Send Beacon’ action, this action ensures data is sent to the appropriate XDM fields which populate Adobe Analytics variables.
Clear Variables - Allows you to clear variable values so they don’t persist to subsequent hits. You may also access this functionality by calling s.clearVars() in the custom code of the Set Variables action or the extension configuration.
Send Beacon - Provides a familiar user interface for sending data to Adobe Analytics. This action does the following:
- Sets the appropriate XDM fields based on the beacon type
- Updates XDM for the variables in Global Settings
- Runs the doPlugins function (if it exists and s.usePlugins is true)
- Triggers Alloy.js's sendEvent functionality.
Set Product String - Provides a clean User interface to set all aspects of the Adobe Analytics products string. This action works exactly like the AA Product String Builder extension. See the documentation here.
At runtime, this extension adds two properties to the AEP Web SDK instance (alloy). In the developer console, take a look at the following:
alloy.xdmStatethis object contains all of the XDM data that is created by the extension's configuration and actions. Note that the Clear Variables action will cause this object to be reset (the same is true of calling s.clearVars() from within custom code.
alloy.legacySthis object provides setters, getters and various utility functions (getEvent, setEvent, removeEvent, clearVars, etc). It is the same object that is provided as 's' within the custom code editors in the UI.
Both of these objects are reactive and can be viewed or modified from the developer console. Changing the properties of one will cause changes in the other (they are essentially just two sides of the same coin).
alloy.util.deepGetis a function provided by this extension that can be used to safely and easily access the values of any deeply pathed field within an object. It takes two arguments; the first is the object that you wish to get a value from; the second is the path to that field. This function will return undefined if any part of the path does not exist or does not have a value. An example of this is
let eVar1Value = alloy.util.deepGet(alloy.xdmState, '_experience.analytics.customDimensions.eVars.eVar1');
alloy.util.deepSetis a function provided by this extension that can be used to safely and easily set values for deeply nested paths. This function takes three values; the first is the object that you wish to set a value on; the second is the path to that field; the third is the value that you wish to set for that field. When setting the value, any paths that are specified but do not yet exist will be created. An example of this is:
alloy.util.deepSet(alloy.xdmState, '_experience.analytics.customDimensions.eVars.eVar111', 'foo')
alloy.util.deepUnSetis a function provided by this extension that can be used to safely and easily unset values for deeply nested paths. It takes two arguments; the first is the object that you wish to unset a value from; the second is the path to that field. Note that this function will only remove the leaf node. An example of this is
Lifecycle and management of alloy.xdmState