Unlocking User Insights: How to configure Analytics in your Constellation Application

[RichardMarsot]

When you build applications in Pega Constellation, understanding how end users navigate your portals, complete assignments, and encounter bottlenecks is crucial for continuous improvement. To get these insights, organizations rely on web analytics solutions.

Integrating analytics into a modern, single-page Pega application requires a slightly different approach than traditional websites. This guide breaks down what analytics tools do, why Pega Constellation requires an event-driven strategy, and how to set up a robust integration using Google Tag Manager and Google Analytics 4.

1. What Are Analytics Solutions and How Do They Work?

Think of an analytics solution as a digital tape measure and activity log for your software. It records how many people visit your application, where they click, how long they stay on a screen, and where they get stuck or drop off.

Popular enterprise vendors include:

• Google Analytics 4 (GA4): Focuses on user sessions, traffic paths, and overall system usage metrics.
• Pendo: Specializes in product adoption, in-app guidance, and detailed feature click tracking.
• Mixpanel & Heap: Event-centric platforms built for deep user behavior and journey funnel analysis.

How Traditional Analytics Works

On a standard web page (like an online news site or blog), every time you click a link, your browser reloads a completely new HTML page. Analytics scripts naturally wake up on each page load, record the URL, and send a “Page View” event to a reporting dashboard.

2. The Pega Constellation Difference: Why Page-Based Tracking Fails

Constellation is built as a Single-Page Application (SPA). In an SPA, the browser loads the application framework once. When a user opens a case, switches tabs, or submits a form, the screen updates dynamically without reloading the entire web page. Because the browser page never “reloads,” standard analytics tools will miss almost all user activity if they rely solely on traditional URL changes.

The Solution: Event-Driven Tracking

Instead of waiting for page reloads, Constellation provides an internal event system known as PCore (specifically PCore.getPubSubUtils()). When an assignment opens, a stage changes, or a view finishes rendering, Constellation broadcasts an internal event. By subscribing to these events with a custom script, you can capture exact user interactions in real time.

3. The Universal Strategy for Any Analytics Vendor

Regardless of whether you choose Google Analytics, Pendo, or Adobe Analytics, the high-level strategy for Pega Constellation remains identical:

[ Pega App Head ] ──► Loads Vendor Script (e.g., GTM / Pendo SDK)

    │

[ Analytics.js ] ──► Listens to Pega PCore Events (SHOW_PAGE_DONE, CASE_OPENED)

    │

[ Data Layer ] ──► Passes Cleaned Events to Vendor Dashboard

Step 1: Embed the Vendor Script

Load the vendor’s core tracking snippet in the of your application. In Pega, this is commonly done by overriding or referencing rules such as pyPortalIcon or embedding script tags in your application harness wrapper.

Step 2: Use a Dedicated External JavaScript File

Rather than writing inline code directly inside Pega HTML rules, maintain your event listener logic in a separate JavaScript file (such as Analytics.js) stored as a webwb static file rule in Pega.

Here is a generic javascript file that used PCore to subscribe to the event - you can use it as a starting point:

Generic_Analytics.txt (4.9 KB)

Storing code in a dedicated .js rule offers major advantages:

• Code Quality & Linting: You can pass the script through JavaScript validation tools (ESLint) to catch syntax errors before deployment.
• Version Control & Maintenance: Updates to tracking logic can be made cleanly in a single place without altering core UI components.

Critical Safeguards & Limitations to Consider

• Personally Identifiable Information (PII): Enterprise privacy regulations strictly forbid sending sensitive data (like Social Security Numbers, passwords, or customer email addresses) to analytics platforms. Your script must actively filter and redact sensitive fields from event payloads.
• Payload Flattening: Pega event payloads contain deeply nested JavaScript objects. Most analytics tools require simple, flat key-value pairs (e.g., page_name: “Create Claim”) rather than nested objects.
• Logging vs. Production Performance: Keep debug console logs disabled by default in production. Excessive console logging can slow down the browser UI.

4. Step-by-Step Setup: Google Analytics 4 & Google Tag Manager

Here is how to connect Pega Constellation to Google Analytics 4 (GA4) using Google Tag Manager (GTM) as the middleman.

Phase A: Configure Google Analytics 4 (GA4) and Google Tag Manager (GTM)

1. Set up Google Analytics 4 (GA4):

   • Create a GA4 Property in Google Analytics.

   • Obtain your Measurement ID (formatted like G-XXXXXXXXXX).

2. Set up Google Tag Manager (GTM):

   • Create a GTM Web Container.

   • Obtain your Container ID (formatted like GTM-XXXXXXX).

   • Link GA4 inside GTM:

     • In GTM, go to Tags > New > Google Analytics (Google Tag).

     • Enter your GA4 Measurement ID (G-XXXXXXXXXX).

     • Set the trigger to Initialization - All Pages.

Phase B: Configure Google Tag Manager (GTM)

1. Create a Data Layer Variable:
   • Go to Variables > User-Defined Variables > New.
   • Name the variable: dlv - pega.
   • Variable Type: Data Layer Variable.
   • Data Layer Variable Name: pega.
   • Click Save.
2. Create a Wildcard Custom Event Trigger:
   • Go to Triggers > New.
   • Trigger Type: Custom Event.
   • Event Name: ^pega_.*
   • Check Use regex matching.
   • Name it Pega Events Wildcard and Save.
3. Create the GA4 Event Tag:

   • Go to Tags > New.

   • Tag Type: Google Analytics > Google Analytics: GA4 Event.

   • Measurement ID: Enter your GA4 ID (e.g., G-XXXXXXXX).

   • Event Name: Click the + icon and select {{Event}} (this dynamically forwards event names like pega_page_done or pega_case_created).

   • Under Event Parameters, add:

     • Parameter Name: pega_data
     • Value: {{dlv - pega}}

   • Under Triggering, attach your Pega Events Wildcard trigger.

   • Name the tag GA4 - Pega Events and Save.

   • 

   • You can also create a Google Analytics tag - you would end up with the following configuration:

     

Phase C: Configure Pega Constellation

1. Load the Scripts in Your Portal:
   Include the GTM container script and reference your custom JS rule in your portal header by editing the pyPortalIcon HTML fragment and saving it in your application - the script snippet is provided by Google and might change. Also this fragment is loaded by ANY portals - you might want to conditionalize the loading based on the portal name or url

   snippet-pyportalicon.txt (755 Bytes)

   

2. Add the Event Listener Logic (Analytics.js):
   Your JavaScript file waits for PCore to load, subscribes to Constellation PubSub events, and pushes sanitized data to window.dataLayer:

   Analytics.txt (6.9 KB)

5. Privacy, Cookie Consent, and Next Steps

Before pushing any analytics solution to production, privacy compliance must be guaranteed.

Cookie Consent & GDPR Disclaimers

Analytics tools typically store cookies or local storage identifiers in the user’s browser to measure unique sessions across visits. Under privacy regulations like GDPR (Europe) or CCPA (California), applications must obtain explicit user consent before dropping tracking cookies or capturing behavioral data.

• Default Behavior: While Pega Constellation provides out-of-the-box cookie consent banner components, a basic custom event listener script does not automatically respect user opt-in/opt-out status on its own.
• Required Wiring: You must bridge your event script with Google Consent Mode v2 or ensure your Analytics.js listener checks consent state before firing dataLayer.push() statements.

Production Execution Checklist

To ensure a robust, enterprise-grade analytics rollout:

1. Define a Data Governance Plan: Establish strict naming conventions for custom dimensions (e.g., page_name, case_class, assignment_name) so reports remain organized as new cases are added.
2. Register Custom Dimensions in GA4: Ensure parameters sent inside pega_data are registered in GA4 under Admin > Custom Definitions so they can be queried in reports.
3. Verify Compliance: Test that PII filtering works by attempting to trigger mock events containing test emails or account numbers, verifying they appear redacted in analytics output.
4. Validate in Staging: Always inspect live events using GTM Preview Mode and GA4 DebugView before publishing container changes to production.

[MarcCheong]

Another great Knowledge Share @RichardMarsot! I have added it to our constellation 101 series.

Enjoyed this article?

See suggested articles from our Constellation 101 series and view all our Knowledge Shares from our User Experience Expert Circle.