The new Dynamic Media Viewers extension for Platform Launch and Dynamic Media Viewers 5.13, lets customers of Adobe Analytics and Platform Launch to use events and data specific for the Viewers in their Platform 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 Experience Platform Launch extension that comes from Adobe or a third party.
To learn more about extensions, see Adobe Extension in the Experience Platform Launch User Guide.
This topic is intended for the following: Site administrators, Developers on the Experience Manager Platform, and people in Operations.
The primary use case for the integration with Experience Platform Launch is customers who use both AEM Assets and AEM Sites. In such scenarios, you can set up a standard integration between your AEM author node and Experience Platform Launch, then associate your Sites instance with the Experience Platform 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 Experience Platform Launch library production URL from Experience Platform 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, and video play actions.
In Experience Platform Launch, the concepts of Data Elements and Rules work together to enable Adobe Analytics tracking.
A Data Element in Experience Platform 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 more extensions must 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 Experience Platform Launch UI, using Data Element picker widget. In particular, Data Elements defined for the purposes of Dynamic Media Viewers tracking is referenced by Set Variables Action of Adobe Analytics extension in Rule (see below).
See Data elements.
A Rule in Experience Platform Launch is an agnostic configuration that defines three areas that make up a rule: Events, Conditions, and Actions:
Options that are available in the Events, Conditions, and Actions section depend on the extensions that are installed in Experience Platform 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. Those actions include focus change, key presses, and form submissions. 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 other extensions must be installed, as described in Installation and setup of extensions. Specifically:
To track Dynamic Media viewers, it is possible to use any type of the following:
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 Experience Platform Launch demonstrates how to track an asset name on viewer load.
From the Data Elements tab, define a data element
AssetName that references
asset parameter of the
LOAD event from the Dynamic Media Viewers extension.
From the Rules tab, define a rule TrackAssetOnLoad.
In this rule, the Event field uses the LOAD event from the Dynamic Media Viewers extension.
The Action configuration has two Action types from the Adobe Analytics extension:
Set Variables, which map an analytics variable of your choice to the value of
AssetName Data Element.
Send Beacon, which sends tracking information to Adobe Analytics.
The resulting rule configuration looks like the following:
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 Experience Platform 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 Experience Platform 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 Experience Platform Launch integration.
Following proper configuration, you can add Experience Platform Launch support to a web page with a Dynamic Media viewer.
See Add the Platform Launch Embed Code to learn more about how to use Experience Platform Launch library embed code.
To track Dynamic Media viewers using embed code:
The Dynamic Media Viewer extension automatically integrates with the Experience Platform Launch library if the following conditions below are true:
Experience Platform Launch library global object (
_satellite) is present on the page.
The Dynamic Media Viewers extension function
_dmviewers_v001() is defined on
config2= viewer parameter is not specified, which means that viewer does not use legacy Analytics integration.
Also, there is an option to explicitly disable Experience Platform Launch integration in the viewer by specifying
launch=0 parameter in the viewer’s configuration. The default value of this parameter is
The only configuration option for the Dynamic Media Viewers extension is Enable Adobe Media Analytics for Audio and Video.
When you check (enable) this option, and the Adobe Media Analytics for Audio and Video extension is installed and configured, video playback metrics are sent to the Adobe Analytics for Audio and Video solution. Disabling this option turns off video tracking.
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:
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 subsection. Currently, the Dynamic Media Viewers reference guide does not document event arguments.
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, suppose the Data Element points to the LOAD event and its “asset” argument. In such case, the value of such Data Element receives 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 remains 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, suppose the Data Element ZoomScale is defined for “scale” parameter of the ZOOM event. However, 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 tracks the value itself, and the viewer that has populated the value. For example, suppose that there are several viewers on the same page, and 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, the Data Element is requested in a Rule that was triggered by an Event from some other Platform Launch extension. At that point, the value of the Data Element comes from the viewer that was last to update this Data Element.
Consider the following sample setup:
A web page that has two Dynamic Media zoom viewers: viewer1 and viewer2.
ZoomScale Data Element points to the ZOOM event and its “scale” argument.
TrackPan Rule with the following:
TrackKey Rule with the following:
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 select a key on the keyboard.
The end user’s activity results in the following two tracking calls being made to Adobe Analytics:
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 the Platform Launch library code even after the viewer itself is disposed on the web page. This functionality 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 Experience Platform 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 editor 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 an 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:
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. Enter the fully qualified name of the event argument in the value input field of the Analytics variable assignment. Be sure you surround it with percent (%) signs. For example,
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. For example, clicking 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.
The following table lists Dynamic Media Viewer events and their supported arguments:
|Viewer event name||Argument reference|
BEFORE YOU BEGIN
Adobe recommends that you thoroughly review all documentation before 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 Experience Platform Launch is possible, such scenarios are not covered in this documentation.
You are going to use the following Adobe products to configure your integration:
Also, if this integration solution is used with Experience Manager Sites, the following configuration must also be done:
As part of the configuration, be sure you have access to a company in Adobe Experience Cloud that has Adobe Analytics and Experience Platform Launch already enabled.
After you configure Adobe Analytics, the following will be set up for the integration:
See also Analytics Implementation Guide.
To configure Adobe Analytics for the integration:
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.
Now select a report suite.
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 is up to you.
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.
Now set up Adobe Analytics variables.
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]) is driven by the specific needs of your Analytics implementation.
For the purposes of this documentation, only a Custom Traffic (props) variable will be used because they become available in an Analytics Report within a few minutes after an action occurs on a web page.
To enable a new Custom Traffic variable, in Adobe Analytics, in the toolbar, click Admin > Report Suites.
On the Report Suite Manager page, select the correct report, then in the toolbar, click Edit Settings > Traffic > Traffic Variables.
There, pick an unused variable, give it a descriptive name ( Viewer asset (prop 30)) and change combo box to “Enabled” in the Enabled column.
The following screenshot is an example of a Custom Traffic variable ( prop30) for tracking an asset name used by the viewer:
At the bottom of the variables list, click Save.
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 set up 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 Experience Platform Launch, the following will be set up for the integration:
To configure Experience Platform Launch for the integration:
Start by accessing Experience Platform Launch from the Experience Cloud home page. On the menu bar, click the Solutions icon (three by three table of dots) near the upper-right corner of the page, then click Launch.
You can also open Experience Platform Launch directly.
A property in Experience Platform 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 Launch Property.
In Experience Platform Launch, click New Property.
In the Create Property dialog box, in the Name field, type a descriptive name, such as the title of your website. For example,
In the Domains field, enter your website’s domain.
In the Advanced Options drop-down, enable Configure for extension development (cannot be modified later) in case the extension you want to use–in this case, Dynamic Media Viewers–is not yet released.
Click the newly created property then proceed to Installation and setup of extensions.
All available extensions in Experience Platform 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:
No additional configuration is needed, accept for any proposed values. When you are done, be sure you click Save.
To configure this extension, you 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 is 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> is the information obtained in the provisioning email.
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> is the information from the provisioning email.
All other fields are optional.
Select enable Adobe Analytics for Video to enable (turn on) Video Heartbeat tracking.
As of this writing, the Dynamic Media Viewers extension is only available if the Experience Platform 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 Experience Platform 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 Experience Platform Launch.
See Sample configuration for a sample configuration in Experience Platform 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 change the Experience Platform Launch configuration (including Property, Extensions, Rules, and Data Elements set up), you must publish such changes. Publishing in Experience Platform Launch is performed from the Publishing tab under the Property configuration.
Platform Launch can potentially have multiple Development environments, one Staging environment, and one Production environment. By default the Platform Launch Cloud Configuration in Experience Manager points the Experience Manager author node to the Stage environment of Platform Launch. The Experience Manager publish node points to the Production environment of Platform Launch. This arrangement means that with the default Experience Manager settings, it is necessary to publish the Platform Launch library to the Staging environment. Doing so lets you use it in Experience Manager author. You can then publish it into the Production environment so that it can be used in Experience Manager publish.
See Environments for more information about Experience Platform Launch environments.
Publishing a library involves the following two steps:
The first time you open the Publishing tab in Experience Platform Launch, the library list is empty.
In the left column, click Add New Library.
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 a few minutes, the library is created and ready to use.
The next time you change your Experience Platform 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.
After a new library is added, it is found in the Development environment. To move it to the Staging environment level (which corresponds to the Submitted column), from the library’s drop-down menu, click Submit for Approval.
In the confirmation dialog box, click Submit.
After the library moves to the Submitted column, from the library’s drop-down menu, click Build for Staging.
To move the library from the Staging environment to the Production environment (which is the Published column), follow a similar process.
First, from the drop-down menu, click Approve for Publishing.
From the drop-down menu, click Build & Publish to Production.
See Publishing for more information about the publishing process in Experience Platform Launch.
The AEM configuration consists of the following two major steps:
In AEM author, click the Tools icon (hammer), then click Security > Adobe IMS Configurations.
On the Adobe IMC Configuration page, near the upper-left corner, click Create.
On the Adobe IMS Technical Account Configuration page, in the Cloud Solution drop-down list, click Experience Platform Launch.
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 is added to the technical account on Adobe I/O!
To dismiss the Info dialog box, click OK.
To download a public key file (*.crt) to your local system, click Download Public Key.
At this point, leave open the Adobe IMS Technical Account Configuration page; do not close the page and do not click Next. You are going to return to this page later in the steps.
In a new browser tab, navigate to the Adobe I/O Console.
From the Adobe I/O Console Integrations page, near the upper-right corner, click New integration.
In the Create a new integration dialog box, ensure that Access an API radio button is selected, then click Continue.
On the second Create a new integration page, enable (turn on) the Experience Platform Launch API radio button. In the lower-right corner of the page, click Continue.
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>.
Click Create integration.
On the Integration created page, click Continue to integration details.
An Integrations details page appears, [!UICONTROL] similar to the following:
Leave open this Integration details page. You are going to need various pieces of information from the Overview and JWT tabs in just a moment.
Integration details page.
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 closed the page earlier, return to Experience Manager author, then click Tools > Security > Adobe IMS Configurations. Click Create. In the Cloud Solution drop-down list, select Experience Platform Launch. In the Certificate drop-down list, select the name of the previously created certificate.)
Adobe IMS Technical Account Configuration - Certificate page.
The Account page has five fields that you are required to fill out using information from the Integration details page from the previous step.
Adobe IMS Technical Account Configuration - Account page.
On the Account page, fill in the following fields:
Return to the Account page, then paste the name into the respective field.
(the example server name is for illustration purposes only)
Integration detail page - JWT tab
API Key - Return to the Integration details page. Click the Overview tab, then to the right of the API Key (Client ID) field, click Copy.
Return to the Account page, then paste the key into the respective **[!UICONTROL]**field.
Integration details page.
Client Secret- Return to the Integration details page. From the Overview tab, click Retrieve Client Secret. To the right of the Client secret field, click Copy.
Return to the Account page, then paste the key into the respective field.
Payload - Return to the Integration details page. From the JWT tab, in the JWT Payload field, copy the entire JSON object code.
Return to the Account page, then paste the code into the respective field.
Integration details page - JWT tab
The Account page, with all fields filled out, looks similar to the following:
Near the upper-right corner of the Account page, click Create.
With AEM IMS configured, you now have a new IMSAccount listed under Adobe IMS Configurations.
In AEM author, near the upper-left corner, click the Tools icon (hammer), then click Cloud Services > Experience Platform Launch Configurations.
On the Experience Platform Launch Configurations page, in the left panel, select an AEM Site for which you want to apply your Experience Platform Launch Configuration.
For illustration purposes only, the We.Retail Site is selected in the screenshot below.
Near the upper-left corner of the page, click Create.
On the General page (1/3 pages) of the Create Experience Platform 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 Experience Platform Launch property that you created previously. The list populates automatically.
After completing all the fields, your General page will look similar to the following:
Near the upper-left corner, click Next.
On the Staging page (2/3 pages) of the Create Experience Platform Launch Configuration window, fill in the following field:
In the Library URI field, check the location of the staging version of your Experience Platform Launch library. AEM populates this field automatically.
For illustration purposes only, this step uses Experience Platform 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.
Your Staging page likely appears similar to the following. The Archive and Load Library Asynchronously options are not set:
Near the upper-right corner, click Next.
On the Production page (3/3 pages) of the Create Experience Platform Launch Configuration window, if needed, fix the auto-populated production URI similar to how it was done on the previous Staging page.
Near the upper-right corner, click Create.
Your new Experience Platform Launch Cloud Configuration is now created and listed next to your web site similar to the following example:
Select your new Experience Platform Launch Cloud Configuration (a check mark appears to the left of the configuration title when it is selected). On the toolbar, click Publish.
Currently, AEM author does not support the integration of Dynamic Media Viewers with Experience Platform Launch.
It is, however, supported in the Experience Manager publish node. Using the default settings of Platform Launch Cloud Configuration, Experience Manager publish node uses the production environment of Experience Platform Launch. As such, it is necessary to push Experience Platform Launch library updates from Development up to the Production environment each time during the test.
It is possible to work around this limitation. Specify the Development or Staging URL of the Platform Launch library in the Platform Launch Cloud configuration for the Experience Manager publish node above. Doing so makes the Experience Manager publish node use the Development or Staging version of Platform Launch library.
See Integrate AEM with Experience Platform Launch Via Adobe I/O for more information about setting up Experience Platform Launch Cloud Configuration.