How to configure Adobe Analytics data in an IUX slot with filters

This developer-targeted page explains how to display and filter data from Adobe Analytics in a Magnolia IUX slot.

IUX slots are places in the AdminCentral UI where elements from integrated applications or other Magnolia content apps can live. Elements such as charts and widgets add value to the user’s workflow inside Magnolia. We pull in data from adjacent applications and content apps and display it in the right places so that users do not need to switch contexts.

This page covers how to:

Prerequisites

We assume you:

Use case 1: Display a chart showing visits to a page over 7 days

In our first use case, we want to display Adobe analytics in an IUX slot to show how many people visit our page /travel within a 7-day period.

Adobe provides a Reporting API that supports some filtering functionality such as Global Filters and Filtering Reports. However, this functionality does not meet our requirements.

In our example, we want to show the following data:

example IUX slot

The chart, or report, above shows us the number of visits to the page /travel from 30 June to 6 July.

This data is a combination of the dimension variables/daterangeday with the metric metrics/pageviews, filtered using the custom variable variables/evar1 where the item value is /travel

To get this data, we use Breakdown Reports.

Breakdowns in the API are useful when you want to see the cross-product of values from two different dimensions.

When requesting a breakdown report, we use the metricsFilters and dimension parameters to request the additional dimension.

This type of report does not support a filter expression for a dimension value such as contains /travel. Therefore, we must set up a custom eVar dimension to match the stored value of the page path.

Set up custom variables in Adobe Launch

Here are the steps to set up a custom variable in Adobe Launch to store all node paths related to the page visited by users.

In this example, we use a custom variable called eVar1,but you can use any custom variable available that suits your requirements.
  1. In Adobe Launch, add a nodePath Data Element.

    IUX slot

  2. Edit your existing Rules to set up an eVar1 variable

    IUX slot

  3. Make sure you publish every change in Publishing Flow.

  4. Update the Custom JavaScript Variables in your Magnolia site, add the Page_Node_Path variable in your <head> element.

    <script>
     var Page_Node_Path="${content.@path}"; <!-- access variables content by Free marker  ><-->
    </script>
    
    <!-- Add above script before your adobe embed script for tagging><-->
    
    <script src="https://assets.adobedtm.com/aae80178d8f6/e2c5fb7f54b4/launch-03c511c88bcf-development.min.js" async>
    </script>
Example of changes in the MTK template

IUX slot

Example of changes in the Travel template

IUX slot

JavaScript alternative to get the node path

If you don’t want to get the node path using Free marker code, you can replace it with JavaScript code to get the node path from the URL path name.

  1. Replace

    <script>
     var Page_Node_Path="${content.@path}";
    </script>

    with

    <script>
    var Page_Node_Path=window.location.pathname.split(";")[0].split(".html")[0];
    </script>
  2. Ensure your script can send eVar1. You can check using the Adobe debugger.

    IUX slot

We recommend you try to fetch your report with Adobe Swagger first to ensure the custom variable eVar1 is working.

Example JSON body request:
{
   "rsid":"emagmgnl",
   "globalFilters":[
      {
            "type":"dateRange",
            "dateRange":"2021-07-01T00:00:00.000/2021-07-05T23:59:59.999"
      }
   ],

   "metricContainer":{
      "metrics":[
         {
            "columnId":"0",
            "id":"metrics/pageviews",
            "filters":[
              "0","1"
            ]
         }
      ],
      "metricFilters":[
         {
            "id":"0",
            "type":"breakdown",
            "dimension":"variables/evar1",
            "itemValue":"/travel"
         },
         {
            "id":"1",
            "type":"dateRange",
            "dateRange":"2021-07-01T00:00:00.000/2021-07-05T23:59:59.999"
         }
      ]
   },
   "dimension":"variables/daterangeday",
   "settings":{
      "dimensionSort":"asc"
   }
}

Use case 2: Display a chart showing visits to all pages with a given path name over 7 days

In our second use case, we want to display Adobe analytics in an IUX slot to show the Total visits to all pages containing /travel over a 7-day period.

For this use case, you follow the same steps as in use case 1 with some changes when preparing the data elements.

  1. In Adobe Launch, add a pathName Data Element.

    Add a data element

  2. Edit your existing Rules to set up the eVar2 variable.

    In this example, we use a custom variable called eVar2,but you can use any custom variable available that suits your requirements.

    Edit rules

  3. Ensure your script can send eVar2 by Adobe debugger

We recommend you try to fetch your report with Adobe Swagger first to ensure the custom variable eVar2 is working.

Example JSON body request:
{
   "rsid":"emagmgnl",
   "globalFilters":[
      {
            "type":"dateRange",
            "dateRange":"2021-07-01T00:00:00.000/2021-07-05T23:59:59.999"
      }
   ],

   "metricContainer":{
      "metrics":[
         {
            "columnId":"0",
            "id":"metrics/pageviews",
            "filters":[
              "0"
            ]
         }
      ],
      "metricFilters":[
         {
            "id":"0",
            "type":"dateRange",
            "dateRange":"2021-07-01T00:00:00.000/2021-07-05T23:59:59.999"
         }
      ]
   },
   "dimension":"variables/evar2",
   "settings":{
      "dimensionSort":"asc"
   }
}

Configure your Magnolia Adobe Analytics IUX slot for the use cases above

In Magnolia, you then prepare the YAML configuration so that the Adobe connector datasupplier can get the breakdown report.

Make sure you configure the correct eVar dimension.
pages-app.subApps.browser.workbench.yaml
  extensionViews:
  - name: analytics
    icon: icon-analytics-app
    view:
      name: analytics
      $type: analyticsView
      chartDefinitions:
        - name: usecase1
          label: "Adobe Page Views With Metric Filters"
          class: info.magnolia.analytics.amcharts.data.AmChartDefinition
          dataSupplier: adobeMetricFilterDataSupplier
          chartType: !include:/analytics-ui/chartTypes/line-and-area/line-different-colors-ups-downs.yaml
            series:
              - name: series
                dataFields:
                  - name: categoryX
                    jsonPath: "$.rows[*].value"
                  - name: valueY
                    jsonPath: "$.rows[*].data[0]"
            xAxes: !override
              - name: xaxe
                renderer:
                  labels:
                    truncate: true
                    maxWidth: 90
        - name: usecase2
          label: "Total Adobe Page Views"
          class: info.magnolia.analytics.amcharts.data.AmChartDefinition
          dataSupplier: adobePageViewsDataSupplier
          chartType: !include:/analytics-ui/chartTypes/line-and-area/line-different-colors-ups-downs.yaml
            series:
              - name: series
                dataFields:
                  - name: categoryX
                    jsonPath: "$.rows[*].value"
                  - name: valueY
                    jsonPath: "$.rows[*].data[0]"
            xAxes: !override
              - name: xaxe
                renderer:
                  labels:
                    truncate: true
                    maxWidth: 90 #maxWidth can be changed depending on to your config, exp: 120 instead of 90
      dataSuppliers:
        adobeMetricFilterDataSupplier:
          class: info.magnolia.analytics.adobe.datasource.AdobeDataSupplier
          credentials:
            parameters:
              serviceUrl: https://analytics.adobe.io/api/xxxxxxxxxxxx/reports
              clientId: <your-client-id>
              clientSecret: <client_secret_or_path_to_password_manager>
              companyId: <your-company-id>
              orgId: xxxxxxx@AdobeOrg
              technicalAccountId: xxxxxx@techacct.adobe.com
              imsHost: https://ims-na1.adobelogin.com
              imsExchange: https://ims-na1.adobelogin.com/ims/exchange/jwt
              privateKeyPath: /bca-common/adobe/secret.key
              metascopes: ent_analytics_bulk_ingest_sdk
              tokenExpTime: 3600
          parameters:
            rsid: xxxxxxxx
            gFilterType: dateRange
            metricId: metrics/pageviews
            dimension: variables/daterangeday
          metricFiltersExpression:
            - id: 0
              type: breakdown
              dimension: variables/evar1 #This is just an example, the variable needs to be configured to map with pageName or pageUrl
              itemValue: "%s" # %s is selected node path. Ex: /travel
        adobePageViewsDataSupplier:
          class: info.magnolia.analytics.adobe.datasource.AdobeDataSupplier
          credentials:
            parameters:
              serviceUrl: https://analytics.adobe.io/api/xxxxxxxxxxxx/reports
              clientId: xxxxxxxx
              clientSecret: /AdobeAnalytics/ClientSecret
              companyId: xxxxxxx
              orgId: xxxxxxx@AdobeOrg
              technicalAccountId: xxxxxx@techacct.adobe.com
              imsHost: https://ims-na1.adobelogin.com
              imsExchange: https://ims-na1.adobelogin.com/ims/exchange/jwt
              privateKeyPath: /bca-common/adobe/secret.key
              metascopes: ent_analytics_bulk_ingest_sdk
              tokenExpTime: 3600
          parameters:
            rsid: xxxxxxxx
            gFilterType: dateRange
            metricId: metrics/pageviews
            dimension: variables/evar2
          filteringSubSetExpression:
            clause: CONTAINS '%s' #selected node path
      filterFields:
        - name: startDate
          $type: dateField
        - name: endDate
          $type: dateField
Feedback