Pega® Web Analytics Component Overview Component

Pega® Web Analytics Component

PEGASYSTEMS PROVIDES THIS SOFTWARE 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NONINFRINGEMENT. IN NO EVENT WILL PEGASYSTEMS, THE AUTHORS, OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THIS SOFTWARE OR THE USE OR OTHER DEALINGS IN THIS SOFTWARE. Overview

In order to provide a basic Web Analytics configuration as an interface between Pega7 and individual vendors, Pega has created a component with a Web Analytics Landing page and configuration. This document describes how to install and configure your application to use and configure the Web Analytics component. We have examples for 2 vendors: Google and Matomo (Piwik).

Component

Installation

1. Download the Web Analytics component from Exchange 2. Import the component a. Designer Studio > Application > Distribution > Import i. Local file PegaWebAnalytics_XXXX_010101_XXXX.zip 3. This is a Component containing 2 vendors: Google, Matomo (Piwik). Most of the vendor info will be valid, but you will have register with either vendor's server and update the vendor code with the correct vendor url and the unique token you receive. This is discussed below in the Vendor section. 4. Verify you have the component a. Designer Studio > Application > Components i. You should see PegaWebAnalytics as a component

Preflight Optimization

IMPORTANT: If you are using Preflight Optimization, you need to turn it off to test and then re-optimize once you have created a Web Analytic Configuration that you are happy with. So, for now, just turn this off. Once you have a working web analytics test, you can run re-optimization and turn it back on.

Additional Information

After installing the Web Analytics component, you need to log off and back on.

With the component installed, Web Analytics can be found under "User Interface" on the Designer Studio menu.

Selecting Web Analytics will bring up the Web Analytics Landing Page. It is here that you will be able to add, edit, and remove web analytics configurations for different access groups/portals or globally. You can also choose different vendors and use them simultaneously.

Initial display before adding configurations

After adding configurations

Modifying Existing Configurations

Use Web Analytics

Selecting this checkbox will turn on/off web analytics for the given configuration.

NOTE: Changing this setting requires you to log off and log back in to the application(s) in order to for this change to be applied.

Edit

The edit icon will bring up the configuration dialog (same as add analytics) to change the analytics configuration.

NOTE: With edit, you can NOT change the AccessGroup/Portal.

Delete

The delete icon will delete this configuration. It will also remove the Data record associated with this configuration.

NOTE: Delete will NOT remove the Data Vendor record that was used or created with this configuration.

Add analytics

To add an analytics configuration, on the Web Analytics Landing Page, press "Add new".

Access Group

The initial configuration dialog will require you to select an Access Group. The list of Access Groups is limited to the current application you are logged in as. Whichever access group you select, Web Analytics will only be applied to that access group and its default portal.

NOTE: You can have multiple configurations for the SAME access group but for DIFFERENT vendors active that the same time.

As an alternative, you can select "All". This will apply this Web Analytics configuration to ALL applications and ALL portals. Similar, to access groups, you can have multiple ALL configurations for different vendors active at the same time.

NOTE: When any “All” configuration(s) are in use, all Access Group specific configurations will be ignored.

NOTE: At present, “All” will only be applied to those applications that have added this web analytics component. (ie. if the Pega application doesn’t have PegaWebAnalytics component specified on the application rule, no analytics will be taken)

Web Analytics Vendor

After you have selected an Access group, you will need to select a Vendor.

For other vendors, you will need to create a new vendor.

Create New Vendor

To create a new vendor, select "Create new vendor". A small overlay will appear for the name of the vendor. Enter this and press "Submit".

Now if you go back to selecting a Vendor, your new Vendor should appear.

New Vendor Logo

Once you create a new vendor, you can add a Vendor logo, to appear in the landing page. (You can jump to "Select a Vendor", section of this document and come back to this later if you don’t have a logo.)

A logo can be added at any time.

• You must capture the vendor's logo image o preferably with a white background o preferably as a "png" file • Next, create a new Data-Content-Image rule o File Name - should be your vendor's name (as created, without spaces), plus "_logo" (vendorco_logo) o File Type - type of file (preferably "png") o File Path - MUST be "/webanalytics/" • Once created, upload the image and save

There are currently 8 common vendors already included in the PegaWebAnalytics ruleset: Google, Piwik, Matomo, Woopra, IBM, Clicky, Adobe, and WebTrends. These will be used if you select the corresponding vendor. You can use these as examples to create your own.

Select a Vendor

Once you select a vendor, you will be presented with an array of Tabs to enter data to configure this Web Analytics for this Vendor and Access group.

Meta Tags Tab

If Web Analytics is turned on for this access group or “All”, then Meta tags will be inserted in the header if any of the tags Name/Content pairs have values. The Meta tags configuration starts with 5 standard tag names. Others can be added or deleted.

Generation of the above will look like the following:

App Data Tab

On the Application Data tab, you can select what kind of data will be sent to the web analytics vendor for each page that is displayed/updated. The data sent is determined by what is selected on this tab, along with the technical configuration on the Page Tab.

Use

Select "Use" if the data on this page will be sent to the web analytics vendor

Add In Case Info

Select "Add in Case Info" if you want some generic Case Data to be sent to the web analytics vendor. This includes the following, if available:

• Action • Harness • Flow • Task • ID • Activity • Page • Page Class • Section Name

Specific values

In addition, you can specify other values from the clipboard that you want to send. If these values are present at the time the page is loaded, they will be sent. Each entry (Event, Name, Property) can be a string, property or page.property value. The entries correspond to {1}, {2} and {3}, which will be replacement values for the technical configuration on the "Page" tab.

Event gives the vendor a classification of “event”, so this data will be found under “events” with the given name (Both Google and Matomo use this classification)

Name provides the second level of classification – “for this event, we have this element”.

Property corresponds to specific data that found for the “Name”.

In the above example: For the Classification of “Case-Info”, “Stage” has a value of “X” (whatever we find on the clipboard page pyWorkPage.pyCurrentStageLabel”)

The following tabs (Page, Click, Click Post) are vendor-specific functionality. Each vendor has a specific API for usage in the header (page) and other JavaScript (JS) API that we can use for clicks and events.

First Time

When updating the data on these tabs for the first time with a new vendor, the data will be copied to the vendor data record for subsequent uses. After the first update, subsequent updates will only update this configuration (access group/vendor) but NOT the vendor data record. To update the vendor data record, press the edit button next to the vendor drop down. Edit the default configuration for that vendor and submit (see below and in the section “Editing Vendor”). We create the vendor default record so that if you create new configurations, you can get the default configuration and then modify it per web configuration as needed.

Page Tab

For each page that is loaded, determine what data is sent to specific web analytics vendors. Most vendors provide at least 2 pieces of data.

Header Snippet

A snippet of code for the header. This must be enclosed in one or more

Vendor JS function call This is the function to call from Google API to pass category/event/data to. Notice that the order is slightly different then our Application Data order of {1}, {2} and {3}. gtag('event', {2}, { 'send_to' : ['biz', 'both'], 'event_category': {1}, 'event_label': {3}});

Click

For Google, gtag is the API function that is called (asynchronously) with category/action/data. In this example, we are getting this data from pega.webanalytics.getClickData. try { if ( (gtag !== null) && (gtag !== undefined) ) {

var oClickData = pega.webanalytics.getClickData(e, sEventList);

/* GA event */ gtag('event', oClickData.action, { 'send_to' : ['click', 'both'], 'event_category': oClickData.category, 'event_label': oClickData.data }); } } catch(ex) { console.error("Web Analytics Click: Google Analytics issue + <" + ex.message + ">"); }

Click Post

Again, for Google, gtag is the API function that is called (asynchronously) with category/action/data. In this example, we are getting this data from pega.webanalytics.getTraceData.

try { if ( (gtag !== null) && (gtag !== undefined) ) {

var oTraceData = pega.webanalytics.getTraceData(e, executable);

/* GA event */ gtag('event', oTraceData.action, { 'send_to' : ['click', 'both'], 'event_category': oTraceData.category, 'event_label': oTraceData.data });

} } catch(ex) { console.error("Web Analytics Click Post: Google Analytics issue: <" + ex.message + ">"); }

Matomo (formerly Piwik)

Matomo is an open source web analytics package that you can install on a local server. The advantage here is a local on-premise server, so your data doesn’t have to be out on the cloud. You can easily test in-house without an https secure server and your test servers can be behind a firewall and don't need to be exposed to the outside world.

Source can be found here: https://matomo.org (formerly https://piwik.org)

Here are the default code snippets:

Page

Pega Exchange – Web Analytics Component 23 Copyright © 2018 Pegasystems Inc. All Rights Reserved. For Matomo, in the code snippet below there is the server url that you have installed (var u) and then "setSetId" is your "token" (obtained when you register your server with your Matomo server.) In addition, I have added "setUserId". This allows you to segment data based upon user id.

NOTE: The code snippet below was retrieved when the install was "Piwik". Now that it has been renamed to "Matomo", if you install the Matomo server, the returned code snippet may have changed. Below is an example of the code snippet retrieved from the Piwik server upon registration.

Vendor Header Snippet

Vendor JS function call For Matomo (Piwik), the JS API is _pag.push(functionName, param1, param2, param3). In general, we are using the "trackEvent" function and ignoring the 4th

NOTE: For Matomo, you call functions by putting the function name, followed by a list of parameters, comma separated, on a stack push.

_paq.push(['trackEvent', {1}, {2}, {3}]);

Click

For Matomo (Piwik), trackEvent is the API function that is called (asynchronously) with category/action/data. In this example, we are getting this data from pega.webanalytics.getClickData. trackEvent is wrapped in the stack _paq, along with its parameters.

try {

if ((_paq !== null) || (_paq !== undefined)) { var oClickData = pega.webanalytics.getClickData(e, sEventList); _paq.push(['trackEvent', oClickData.category, oClickData.action, oClickData.data]);

} else { console.debug("no _paq"); } } catch (ex) { console.error("piwik issue") }

Click Post

For Matomo (Piwik), trackEvent is the API function that is called (asynchronously) with category/action/data. In this example, we are getting this data from pega.webanalytics.getTraceData. trackEvent is wrapped in the stack _paq, along with its parameters. try { Pega Exchange – Web Analytics Component 25 Copyright © 2018 Pegasystems Inc. All Rights Reserved.

if ((_paq !== null) || (_paq !== undefined)) { var oTraceData = pega.webanalytics.getTraceData(e, executable); _paq.push(['trackEvent', oTraceData.category, oTraceData.action, oTraceData.data]); } else { console.debug("no _paq"); } } catch(ex) { console.error("piwik issue") }

Videos

There are 6 sample videos utilizing Google Analytics to show the different functionality configuration:

• WA_MetaTag.mov – shows configuration of “Meta tags” and the end result in the HTML • WA_CaseInfo.mov – shows finding the Google script on the Google Analytics web site matches our configuration, then turning on “Case Info” and seeing the end results • WA_ClipboardData.mov – shows returning Clipboard Data for analytics • WA_Click.mov – shows turning on “Click” and retrieving data associated with clicks (buttons, links, etc.) • WA_FilterTestID.mov – shows turning on “Click” data, but filtering it so that only elements with a specific “test id” will be retrieved. Also shows where the “test id” is located in the HTML. • WA_ClickPost.mov – shows turning on “Click Post” data. This shows the end results of a click (as “dequeue”) more for debugging purposes. For example, the click might call a “runScript” and a “refresh”. NOTE: you won’t see order, but will see the event, along with some associated data and number of times called.