The new Dynamic Media Viewers extension for Adobe Launch, along with the recent release of Dynamic Media Viewers 5.13, lets customers of Dynamic Media, Adobe Analytics, and Adobe Launch to use events and data specific for the Dynamic Media Viewers in their Adobe Launch configuration.
This integration means that you can track usage of Dynamic Media Viewers on your website with Adobe Analytics. At the same time, you can use the events and data exposed by the viewers with any other Launch extension that comes from Adobe or a third-party.
See Adobe Extension in the Experience Platform Launch User Guide to learn more about extensions.
Who should read this documentation: Site administrators, Developers on the AEM platform, and those in Operations.
- Adobe Launch integration for Dynamic Media viewers does not work in the AEM author node. You cannot see any tracking from a WCM page until it is published.
- Adobe Launch integration for Dynamic Media viewers is not supported for "pop-up" operation mode, where the viewer URL is obtained using the "URL" button on Asset Details page.
- Adobe Launch integration cannot be used simultaneously with legacy viewers Analytics integration (by way of the config2= parameter).
- Support for video tracking is limited to core playback tracking only, as described in Tracking Overview. In particular, QoS, Ads, Chapter/Segments, or Errors tracking is not supported.
- Storage Duration configuration for Data Elements is not supported for Data Elements using the Dynamic Media Viewers extension. Storage Duration must be set to None.
The primary use case for the integration with Adobe Launch are customers who use both AEM Assets and AEM Sites. In such scenarios, you can setup a standard integration between your AEM author node and Adobe Launch, then associate your Sites instance with the Adobe Launch property. After that, any Dynamic Media WCM component added to a Sites page will track data and events from viewers.
A secondary use case that the integration supports are those customers who use AEM Assets only, or Dynamic Media Classic. In such cases, you obtain the embed code for your viewer and add it to the website page. Then, get the Adobe Launch library production URL from Adobe Launch and manually add it to the web page code.
The integration takes advantage of two separate and independent types of Dynamic Media Viewers tracking: Adobe Analytics and Adobe Analytics for Audio and Video.
Adobe Analytics lets you track actions that are performed by the end user when they interact with Dynamic Media Viewers on your website. Adobe Analytics also lets you track viewer-specific data. For example, you can track and record view load events along with the asset name, any zoom actions that occurred, video play actions, and so on.
In Adobe Launch, the concepts of Data Elements and Rules work together to enable Adobe Analytics tracking.
A Data Element in Adobe Launch is a named property whose value is either statically defined, or dynamically calculated based on the state of a web page or Dynamic Media Viewers data.
For Adobe Analytics tracking several additional extensions need to be installed, as described in Installation and setup of extensions. Dynamic Media Viewers extension adds an ability to define a Data Element which value is an argument of the Dynamic Viewer event. For example, it is possible to reference the viewer type, or asset name reported by the viewer on load, the zoom level reported when end user zooms and much more.
Dynamic Media Viewer extension automatically keeps the values of its Data Elements up-to-date.
After you have defined it, a Data Element can be used in other places of Adobe Launch UI, using Data Element picker widget. In particular, Data Elements defined for the purposes of Dynamic Media Viewers tracking will be referenced by Set Variables Action of Adobe Analytics extension in Rule (see below).
See Data elements in the Experience Platform Launch User Guide to learn more.
A Rule in Adobe Launch is an agnostic configuration that defines three areas that make up a rule: Events, Conditions, and Actions:
- Events (if) tell Adobe Launch when to trigger a Rule.
- Conditions (if) tell Adobe Launch what additional restrictions to allow or disallow when triggering a Rule.
- Actions (then) tell Adobe Launch what to do when a Rule is triggered.
Options that are available in the Events, Conditions, and Actions section depend on the extensions that are installed in Adobe Launch Property. The Core extension is preinstalled and is available out-of-the-box in any configuration. The extension provides several options for Events such as basic browser-level actions that include focus change, key presses, form submissions, and so on. It also includes options for Conditions, such as cookie value, browser type, and more. For Actions, only the Custom Code option is available.
For Adobe Analytics tracking, several additional extensions must be installed, as described in Installation and setup of extensions. Specifically:
- Dynamic Media Viewers extension extends the list of supported Events to events that are specific to Dynamic Media viewers such as viewer load, asset swap, zoom in, and video play.
- Adobe Analytics extension extends the list of supported Actions with two actions that are required for sending data to tracking servers: Set Variables and Send Beacon.
To track Dynamic Media viewers it is possible to use any type of the following:
- Events from Dynamic Media Viewers extension, Core extension, or any other extension.
- Conditions in the Rule definition. Or, you can leave the conditions area empty.
In the Actions section, it is required that you have a Set Variables action. This action tells Adobe Analytics how to populate tracking variables with data. At the same time, the Set Variables action does not send anything to the tracking server.
The Set Variables action must be followed by a Send Beacon action. The Send Beacon action actually sends data to the analytics tracking server. Both actions, Set Variables and Send Beacon, come from the Adobe Analytics extension.
The following sample configuration within Adobe Launch demonstrates how to track an asset name on viewer load.
When an Experience Cloud account is subscribed to use Adobe Analytics for Audio and Video, it is enough to enable video tracking in the Dynamic Media Viewers extension settings. Video metrics become available in Adobe Analytics. Video tracking depends on the presence of Adobe Media Analytics for Audio and Video extension.
Currently, the support for video tracking is limited to "core playback" tracking only, as described in Tracking Overview. In particular, QoS, Ads, Chapter/Segments, or Errors tracking is not supported.
As mentioned in Use cases for the integration, it is possible to track Dynamic Media viewers with the new Adobe Launch integration in AEM Sites and by using embed code.
To track Dynamic Media viewers in AEM Sites, all steps listed under the Configuring all the integration pieces section must be performed. Specifically, you must create the IMS configuration and the Adobe Launch Cloud Configuration.
Following proper configuration, any Dynamic Media viewer that you add to a Sites page, using a WCM component supported by Dynamic Media, automatically tracks data to Adobe Analytics, or Adobe Analytics for Video, or both.
Customers who do not use AEM Sites, or embed Dynamic Media viewers into web pages outside of AEM Sites, or both, can still use the Adobe Launch integration.
Following proper configuration, you can add Adobe Launch support to a web page with a Dynamic Media viewer.
See Add the Launch Embed Code to learn more about how to use Adobe Launch library embed code.
See Embedding the Video or Image Viewer on a Web Page to learn more about how to use the embed code feature of AEM Dynamic Media.
The Dynamic Media Viewer extension automatically integrates with the Adobe Launch library if all of the following conditions below are true:
- Adobe Launch library global object (_satellite) is present on the page.
- The Dynamic Media Viewers extension function _dmviewers_v001() is defined on _satellite.
- config2= viewer parameter is not specified, which means that viewer does not use legacy Analytics integration.
Additionally, there is an option to explicitly disable Adobe Launch integration in the viewer by specifying launch=0 parameter in the viewer's configuration. The default value of this parameter is 1.
The only configuration option for the Dynamic Media Viewers extension is Enable Adobe Media Analytics for Audio and Video.
When you check (enable or "turn on") this option, and if Adobe Media Analytics for Audio and Video extension is installed and properly configured, video playback metrics are sent to the Adobe Analytics for Audio and Video solution. Disabling this option turns off video tracking.
Note that if you enable this option without having Adobe Media Analytics for Audio and Video extension installed, the option has no effect.
The only Data Element type that the Dynamic Media Viewers extension provides is Viewer Event from the Data Element Type drop-down list.
When selected, the Data Element editor renders a form with two fields:
- DM viewers event data type - a drop-down list that identifies all viewer events that are supported by the Dynamic Media Viewers extension which have arguments, plus a special COMMON item. A COMMON item represents a list of event parameters that are common to all type of events sent by the viewers.
- Tracking parameter - an argument of the selected Dynamic Media viewer event.
See the Dynamic Media Viewers reference guide for the list of supported events by each viewer type; go to specific viewer section, then click Support for Adobe Analytics tracking sub-section. Currently, the Dynamic Media Viewers reference guide does not document event arguments.
Let's now consider the life cycle of the Dynamic Media Viewers Data Element. The value of such Data Element is populated after the corresponding Dynamic Media viewer event happens on the page. For example, if the Data Element points to the LOAD event and its "asset" argument, then the value of such Data Element will receive valid data after the viewer runs the LOAD event for the first time. If the Data Element points to the ZOOM event and its "scale" argument, the value of such Data Element will remain empty until the viewer sends a ZOOM event for the first time.
Similarly, the values of Data Elements get automatically updated when the viewer sends a corresponding event on the page. The value update happens even if the particular event is not specified in the Rule configuration. For example, if Data Element ZoomScale is defined for "scale" parameter of the ZOOM event, but the only rule present in the Rule configuration is triggered by the LOAD event, the value of ZoomScale is still updated every time a user runs zoom inside the viewer.
Any Dynamic Media viewer has a unique identifier on the web page. The Data Element keeps track of the value itself, and the viewer that has populated the value. This means that if there are several viewers on the same page, and there is an AssetName Data Element that points to the LOAD event and its "asset" argument, the AssetName Data Element maintains a collection of asset names that are associated with each viewer loaded on the page.
The exact value returned by the Data Element depends on the context. If the Data Element is requested in a Rule which was triggered by a Dynamic Media viewer event, then the Data Element value is returned for the viewer that initiated the Rule. And, if the Data Element is requested in a Rule that was triggered by an Event from some other Adobe Launch extension, then the value of the Data Element is the value from the viewer that was the last to update this Data Element.
Consider the following sample set up:
- A web page that has two Dynamic Media zoom viewers; we will refer to them as viewer1 and viewer2.
- ZoomScale Data Element points to the ZOOM event and its "scale" argument.
- TrackPan Rule with the following:
- Uses the Dynamic Media Viewer PAN event as a trigger.
- Sends the value of ZoomScale Data Element to Adobe Analytics.
- TrackKey Rule with the following:
- Uses the key press event from the Core Adobe Launch extension as a trigger.
- Sends the value of ZoomScale Data Element to Adobe Analytics.
Now, assume the end user loads the web page with the two viewers. In viewer1, they zoom in to 50% scale; then, in viewer2, they zoom in to 25% scale. In viewer1, they pan image around, and finally press a key on the keyboard.
The end user's activity results in the following two tracking calls being made to Adobe Analytics:
- The first call occurs because TrackPan Rule is triggered when the user pans in viewer1. That call sends 50% as a value of ZoomScale Data Element because the Data Element will know that the Rule is triggered by viewer1 and fetch the corresponding scale value;
- The second call occurs because TrackKey Rule is triggered when the user pressed a key on the keyboard. That call sends 25% as a value of ZoomScale Data Element because the Rule was not triggered by the viewer. As such, the Data Element returns the most up-to-date value.
The sample set up above also affects the life span of the Data Element value. The value of the Data Element managed by the Dynamic Media Viewer is stored in Adobe Launch library code even after the viewer itself is disposed on the web page. This means that if there is a Rule that is triggered by a non-Dynamic Media Viewer extension and references such Data Element, the Data Element returns the last known value, even if the viewer is no longer present on the web page.
In any case, values of Data Elements driven by Dynamic Media Viewers are not stored on the local storage or on the server; instead, they are kept only on the client-side Adobe Launch library. Values of such Data Element disappear when the web page reloads.
Generally, the Data Element editor supports storage duration selection. However, Data Elements that use the Dynamic Media Viewers extension only support the storage duration option of None. Setting any other value is possible in the user interface, but the Data Element behavior is not defined in this case. The extension manages the value of the Data Element on its own: the Data Element that maintains the value of the viewer event argument during the entire viewer life cycle.
In the Rule editor, the extension adds new configuration options for the Events editor. Also the provides an option to manually reference event parameters in the Action editor as a short-hand option instead of using preconfigured Data Elements.
In the Event editor, the Dynamic Media Viewers extension adds a new Event Type called Viewer Event.
When selected, the Event editor renders the drop-down Dynamic Media Viewer events, listing all the available events that are supported by Dynamic Media viewers.
The Dynamic Media Viewers extension lets you use event parameters of Dynamic Media viewers to map to analytics variables in the Set Variables editor of the Adobe Analytics extension.
The simplest method to do that is to complete the following two-step process:
- First, define one or more Data Elements, where each Data Element represents a parameter of a Dynamic Media Viewer event.
- Finally, in the Set Variables editor of the Adobe Analytics extension click the Data Element picker icon (three stacked disks) to open the Select Data Element dialog box, then select a Data Element from it.
It is possible, however, to use an alternative approach and bypass Data Element creation. You can directly reference an argument from a Dynamic Media Viewer event by entering the fully qualified name of the event argument in the value input field of the Analytics variable assignment, surrounded by percent (%) signs. For example,
Note that there is an important difference between using Data Elements and direct event argument reference. For Data Element, it does not matter which event triggers the Set Variables action, the event that triggers the Rule can be unrelated to Dynamic Viewer (like a mouse click on the web page from the Core extension). But, when using a direct argument reference it is important to ensure that the event that triggers the rule corresponds to the event argument that it references.
For example, referencing %event.detail.dm.LOAD.asset% returns the correct asset name if the Rule is triggered by the LOAD event of the Dynamic Media Viewer extension. However, it returns an empty value for any other event.
|Viewer event name||Argument reference|
BEFORE YOU BEGIN
If you have not done so already, Adobe recommends that you thoroughly review all documentation prior to this section so you understand the complete integration.
This section explains the configuration steps that are necessary to integrate Dynamic Media viewers with Adobe Analytics and Adobe Analytics for Audio and Video. While use of the Dynamic Media Viewers extension for other purposes in Adobe Launch is possible, such scenarios not covered in this documentation.
You will configure the integration in the following Adobe products:
- Adobe Analytics - you will configure tracking variables and reports.
- Adobe Launch - you will define a Property, one or more Rules, and one or more Data Elements to enable viewer tracking.
Additionally, if this integration solution is used with AEM Sites, the following configuration also needs to be done:
- Adobe I/O Console - integration is created for Adobe Launch.
- AEM author node - IMS configuration and Adobe Launch cloud configuration.
As part of the configuration, be sure you have access to a company in Adobe Experience Cloud that has Adobe Analytics and Adobe Launch already enabled.
After you configure Adobe Analytics, the following will be set up for the integration:
- A Report Suite is in place and selected.
- Analytics Variables are available to receive tracking data.
- Reports are available to view collected data inside Adobe Analytics.
See also Analytics Implementation Guide.
Start by accessing Adobe Analytics from the Experience Cloud home page. On the menu bar, click the Solutions icon (a three by three table of dots) near the upper-right corner of the page, then clicking Analytics.
Near the upper-right corner of the Adobe Analytics page, to the right of the Search Reports field, select the correct report suite from the drop-down list. If there are multiple report suites available and you are unsure which one to use, contact your Adobe Analytics administrator who can help you select which report suite to use.
In the illustration below, a user created a report suite named DynamicMediaViewersExtensionDoc and selected it from the drop-down list. The report suite name is for illustration purposes only; the name of the report suite you ultimately select will differ.
If no report suite is available, you or your Adobe Analytics administrator must create one before you can proceed any further with the configuration.
In Adobe Analytics, report suites are managed under Admin > Report Suites.
You will now designate one or more Adobe Analytics variables that you want to use to track Dynamic Media Viewers behavior on the web page.
It is possible to use any type of variable supported by Adobe Analytics. The decision about the variable type (like Custom Traffic [props], Conversion [eVar]) should be driven by specific needs of you Analytics implementation.
For the purposes of this documentation, only a Custom Traffic (props) variable will be used because they become available in a Analytics Report within a few minutes after an action occurs on a web page.
To enable a new Custom Traffic variable, in Adobe Analytics, on the toolbar, click Admin > Report Suites.
Generally, setting up a Report in Adobe Analytics is driven by specific project needs. As such, detailed report setup is beyond the scope for this integration.
It is, however, enough to know that the Custom Traffic reports become automatically available in Adobe Analytics after you setup Custom Traffic variables in Setting up Adobe Analytics variables.
For example, the report for Viewer asset (prop 30) variable is available from the Reports menu under Custom Traffic > Custom Traffic 21-30 > Viewer asset (prop 30).
Visiting this report right after Viewer asset (prop 30) creation shows no data; that is expected at this point in the integration.
After you configure Adobe Launch, the following will be set up for the integration:
- The creation of a new Property to keep all your configurations together.
- The installation and setup of extensions. The client-side code of all extensions installed in the Property is compiled together into a library. This library is used by the web page later.
- Configuration of Data Elements and Rules. This configuration defines what data to capture from the Dynamic Media viewers, when to trigger the tracking logic, and where to send the viewer's data in Adobe Analytics.
- Publishing of the library.
A property in Adobe Launch is a named configuration that keeps all your settings together. A library of the configuration settings is generated and published to different environment levels (development, staging, and production).
See also Create a Property.
All available extensions in Adobe Launch are listed under the Extensions > Catalog.
To install an extension, click Install. If needed, perform a one-time extension configuration, then click Save.
Where required, the following extensions must be installed and configured:
- (Required) Experience Cloud ID Service extension
No additional configuration is needed, accept for any proposed values. When you are done, be sure you click Save.
- (Required) Adobe Analytics extension
To configure this extension, you will first need the Report Suite ID found in Adobe Analytics, under Admin > Report Suite, under the Report Suite ID column header.
(For demonstration purposes only, the Report Suite ID of the DynamicMediaViewersExtensionDoc Report Suite will be used in the following screenshots. This ID was created and used in Selecting a Report Suite earlier.)
On the Install Extension page, enter the Report Suite ID in the Development Report Suites field, the Staging Report Suites field, and the Production Report Suites field.
Configure the following item only if you plan to use video tracking:
On the Install Extension page, expand General, then specify the Tracking Server. The Tracking Server follows the template <trackingNamespace>.sc.omtrdc.net, where <trackingNamespace> is the information obtained in the provisioning email.
- (Optional; required only if video tracking is needed) Adobe Media Analytics for Audio and Video extension
Fill in the tracking server field. The tracking server for Adobe Media Analytics for Audio and Video extension is different from the tracking server used for Adobe Analytics. It follows the template <trackingNamespace>.hb.omtrdc.net, where <trackingNamespace> is the information from the provisioning email.
All other fields are optional.
- (Required) Dynamic Media Viewers extension
Select enable Adobe Analytics for Video to enable (turn on) Video Heartbeat tracking.
Note that--at the time of this writing--the Dynamic Media Viewers extension is only available if the Adobe Launch Property is created for development.
After the extensions are installed and setup, at minimum, the following five extensions (four if you are not tracking video) will be listed in the Extensions > Installed area.
In Adobe Launch, create Data Elements and Rules that are necessary for tracking Dynamic Media viewers.
See How data and event tracking works in the integration for an overview of tracking with Adobe Launch.
See Sample configuration for a sample configuration in Adobe Launch that demonstrates how to track an asset name on viewer load.
See Configuring the Dynamic Media Viewers extension for in-depth information about the extension's capabilities.
To make changes in the Adobe Launch configuration (including Property, Extensions, Rules, and Data Elements set up), you need to publish such changes. Publishing in Adobe Launch is performed from the Publishing tab under the Property configuration.
Adobe Launch may have multiple Development environments, one Staging environment, and one Production environment. By default the Adobe Launch Cloud Configuration in AEM points the AEM author node to the Stage environment of Adobe Launch, and the AEM publish node to the Production environment of Adobe Launch. This arrangment means that with the default AEM settings, it is necessary to publish the Adobe Launch library to the Staging environment so as to make use of it in AEM author, and then publish it into the Production environment so that it can be used in AEM publish.
See Environments for more information about Adobe Launch environments.
Publishing a library involves the following two steps:
- Adding and building a new library by including all the necessary changes (new ones and updates) into the library.
- Moving the library up through the different environment levels (from Development to Staging and Production)
On the Create New Library page, in the Name field, enter descriptive name for the new library. For example,
From the Environment drop-down list, choose the Environment level. Initially, only the Development level is available for selection. Near the lower-left side of the page, click Add All Changed Resources.
Near the upper-right corner of the page, click Save & Build for Development.
In few minutes the library is created and ready to use.
The next time you make changes to your Adobe Launch configuration, go to the Publishing tab under the Property configuration, then click your previously created library.
From the library publishing screen, click Add All Changed Resources, then click Save & Build for Development.
- AEM runs both Author and Publish instances.
- AEM author node is set up in Dynamic Media - Scene7 run mode (dynamicmedia_s7)
- Dynamic Media WCM components are enabled in AEM Sites.
The AEM configuration consists of the following two major steps:
- Configuration of AEM IMS.
- Configuration of Adobe Launch Cloud.
Enable Create new certificate, then in the text field, enter any meaningful value for your certificate. For example, AdobeLaunchIMSCert. Click Create certificate.
The following Info message is displayed:
To retrieve a valid access token the new certificate's public key must be added to the technical account on Adobe I/O!.
Click OK to dismiss the Info dialog box.
On the third Create a new integration page, do the following:
- In the Name field, enter descriptive name. For example, DynamicMediaViewersIO.
- In the Description field, enter description for the integration.
- In the Public key certificates area, upload your public key file (*.crt) that you downloaded previously in these steps.
- Under the Select a role for Experience Platform Launch API heading, select Admin.
- Under the Select one or more product profiles for Experience Platform Launch API heading, select the product profile named Launch - <your_company_name>.
Return to the Adobe IMS Technical Account Configuration page that you left open previously. In the upper-right corner of the page, click Next to open the Account page in the Adobe IMS Technical Account Configuration window.
(If you accidently closed the page earlier, return to AEM author, then click Tools > Security > Adobe IMS Configurations. Click Create. In the Cloud Solution drop-down list, select Adobe Launch. In the Certificate drop-down list, select the name of the previously created certificate.)
On the Account page, fill in the following fields:
- Title - Enter a descriptive account title.
- Authorization Server - Return to the Integration details page that you opened earlier. Click the JWT tab. Copy the server name--without the path--as highlighted below.
Return to the Account page, then paste the name into the respective field.
For example, https://ims-na1.adobelogin.com/
(the example server name is for illustration purposes only)
On the General page (1/3 pages) of the Create Adobe Launch Configuration window, fill in the following fields:
- Title - Enter a descriptive configuration title. For example, We.Retail Launch cloud configuration.
- Associated Adobe IMS Configuration - Select the IMS configuration that you created earlier in Configuring AEM IMS.
- Company - From the Company drop-down list, select your Experience Cloud company. The list populates automatically.
- Property - From the Property drop-down list, select your Adobe Launch property that you created previously. The list populates automatically.
After completing all the fields, your General page will look similar to the following:
On the Staging page (2/3 pages) of the Create Adobe Launch Configuration window, fill in the following field:
In the Library URI field, check the location of the staging version of your Adobe Launch library. AEM populates this field automatically.
For illustration purposes only, this step will use Adobe Launch libraries that are deployed to Adobe CDN.
Check to make sure that the auto-populated library URI (Uniform Resource Identifier) is not malformed. If necessary, fix it so that the URI represents a protocol-relative URI. That is, it starts from a double forward slash.
For example: //assets.adobetm.com/launch-xxxx.
Your Staging page should look similar to the following. Note that the Archive and Load Library Asynchronously options are not set:
Currently, AEM author does not support the integration of Dynamic Media Viewers with Adobe Launch.
It is, however, supported in the AEM publish node. Using the default settings of Adobe Launch Cloud Configuration, AEM publish uses the production environment of Adobe Launch. As such, it is necessary to push Adobe Launch library updates from Development up to the Production environment each time during the test.
It is possible to work-around this limitation by specifying Development or Staging URL of Adobe Launch library in the Adobe Launch Cloud configuration for AEM publish above. Doing this makes the AEM publish node use the Development or Staging version of Adobe Launch library.
See Integrate AEM with Adobe Launch Via Adobe I/O for more information about setting up Adobe Launch Cloud Configuration.