Skip to main content

Usage Guide

UI Platform LogRocket library standardizes the way we integrate LogRocket into our applications.

Initialization​

To initialize LogRocket using the UI Platform LogRocket library, you can use the initLogRocket function. This function accepts a configuration object where you can specify your LogRocket application ID and other optional settings.

import { initLogRocket } from '@elliemae/pui-logrocket';

initLogRocket({ appId: 'logrocket-app-id' });

Replace logrocket-app-id with your actual LogRocket app ID. You can use window variables to configure LogRocket based on your environment (dev, stage, prod etc.,). See the "Window Variables" section below for more details.

Preventing Duplicate Initialization​

initLogRocket is safe to call multiple times — only the first call initializes LogRocket; subsequent calls are no-ops. This lets each module in a micro-frontend call it without coordinating.

import { initLogRocket } from '@elliemae/pui-logrocket';

initLogRocket({ appId: 'logrocket-app-id' }); // initializes
initLogRocket({ appId: 'logrocket-app-id' }); // no-op

Window Variables​

The UI Platform LogRocket library can be configured using global window variables below, which can be set before making the initLogRocket call.

  • window.emui.logRocketConfig: The main LogRocket configuration object.

This object has following properties:

  • appId (string): LogRocket application ID allocated to the product.
  • enable (boolean): Flag to enable or disable LogRocket in the microapp. Defaults to true. If set to false, LogRocket will not be initialized even if initLogRocket is called. This can be useful for disabling LogRocket in certain environments (e.g., development or staging).
  • localhostEnable (boolean): Flag to enable LogRocket when running on localhost. Defaults to false. When set to true, LogRocket will be enabled on localhost even if the LOGROCKET_ENABLE_ON_LOCALHOST environment variable is not set. This is useful for local development and testing.
  • childDomains (array of strings, optional): Cross-origin child app origins to link sessions with when the page embeds them as iframes.
    • Default: same-origin children stitch automatically with no configuration.
    • Set this when: the page is a parent that embeds cross-origin guest microapps (e.g. https://app.ice.com embedding https://guest.example.com). List each cross-origin child origin.
    • Format: array of full origins (e.g. ['https://guest.example.com']). Bare hostnames, URLs with paths, and non-array values are dropped with a warning.
    • Note: children themselves don't set this option — they need parentDomain (normally auto-detected). Both sides must be configured for cross-origin linking to work.
  • parentDomain (string, optional): Origin of the page that embeds this one. Used by LogRocket to link the child's session to the parent's.
    • Default: auto-detected when the parent uses buildLogRocketQueryParams (covers cross-origin embeds reliably). Same-origin parents are also detected automatically.
    • Set this when: the parent is cross-origin and does not call buildLogRocketQueryParams. Otherwise leave unset.
    • Format: a full origin (e.g. https://parent.example.com). Bare hostnames or URLs with paths are dropped with a warning.
    • Note: do not set this on a top-level page (no parent) — it would tell LogRocket to wait on a parent that doesn't exist and stall session start.
  • rootHostname (string, optional): Cookie scope for stitching sessions across subdomains of the same site (see LogRocket docs).
    • Default: auto-detected as .<last two hostname segments> (e.g. beta.encompass.ice.com → .ice.com). Same-site iframes converge on the same value automatically.
    • Set this when: you want to narrow the cookie scope to a deeper subtree so sessions in that subtree don't merge with the rest of the site (e.g. set .beta.ice.com on app.beta.ice.com to keep beta sessions isolated from prod).
    • Format: must start with . and end with the auto-detected value. A different site, a shallower scope, or a missing leading dot is rejected with a warning.
    • Note: cross-site frame linking is handled by parentDomain/childDomains, not this option.

Proxying LogRocket Calls Through CDN Domain​

LogRocket script loading and data ingestion are proxied through the UI Platform CDN (cdn.mortgagetech.*.ice.com) instead of LogRocket's own servers. This improves ad-blocker resilience and complies with policies that restrict traffic to internal domains.

The CDN domain is auto-detected when the library is loaded from a CDN URL or localhost. No configuration is needed in that case.

Setting CDN Domain for Bundled (npm) Usage​

When the library is imported as an npm package, auto-detection cannot run. Set window.emui.cdnDomain to the correct environment before the library loads:

window.emui = window.emui || {};
window.emui.cdnDomain = 'https://cdn.mortgagetech.q1.ice.com'; // d1, q1, etc.

Verifying Proxying in Browser DevTools​

In the Network tab, requests should go to https://cdn.mortgagetech.<env>.ice.com/... rather than cdn.lr-in-prod.com or r.lr-in-prod.com. If they don't, set window.emui.cdnDomain or load the library from the CDN.

Testing LogRocket Integration from Localhost​

When developing locally, you may want to test LogRocket integration. There are two ways to enable LogRocket on localhost:

Option 1: Environment Variable​

Set the environment variable LOGROCKET_ENABLE_ON_LOCALHOST to true. If you are using a .env file, add the following line:

LOGROCKET_ENABLE_ON_LOCALHOST=true

Option 2: Configuration Flag​

Set the window.emui.logRocketConfig.localhostEnable flag to true before calling initLogRocket:

window.emui = window.emui || {};
window.emui.logRocketConfig = window.emui.logRocketConfig || {};
window.emui.logRocketConfig.localhostEnable = true;

import { initLogRocket } from '@elliemae/pui-logrocket';
initLogRocket({ appId: 'logrocket-app-id' });

LogRocket will be enabled on localhost if either the environment variable or the configuration flag is set to true.

OneTrust consent management platform is the tool used to manage user consent in ICE. When the root microapplication integrates with OneTrust, the UI Platform LogRocket library leverages OneTrust to control LogRocket initialization and session recording based on user consent.

The library implements a two-level consent control system:

  1. LogRocket Initialization (C0002 - Performance Cookies): Controls whether LogRocket is initialized at all

    • If C0002 is not granted, LogRocket will not initialize
    • When OneTrust is not loaded, LogRocket initializes by default

  2. Session Recording (C0003 - Functional Cookies): Controls whether DOM recording is enabled

    • If C0003 is not granted, LogRocket still captures technical data but disables visual session recording
    • Technical data includes: network requests, console logs, JavaScript errors, performance metrics, and custom events

OneTrust should be integrated only in the root microapplication. Child microapplications (e.g., iframes) do not need to integrate with OneTrust directly, as they will inherit the consent status from the root microapplication via URL query parameters (see "Sharing LogRocket information with child micro applications" section below).

OneTrust Integration​

When OneTrust is present, the library waits for the user's consent decision before initializing LogRocket. Both first-time visitors (waits for the consent banner) and returning visitors (uses cached consent) are handled automatically — there's nothing for the consuming app to wire up. If OneTrust signals don't arrive within 10 seconds, the library initializes with whatever consent state is available so LogRocket isn't blocked indefinitely.

The library also applies privacy-focused defaults (input/text sanitization, hidden ARIA attributes, network body redaction). See the Compliance Guide for details.

For local development, set window.emui.dangerouslyOverrideSessionRecordingConsent to true before calling initLogRocket to force session recording on regardless of OneTrust consent. A console warning is logged whenever this override takes effect.

window.emui = window.emui || {};
window.emui.dangerouslyOverrideSessionRecordingConsent = true;
initLogRocket({ appId: 'logrocket-app-id' });

Only true overrides consent. Any other value — including false — is a no-op: the library falls through to the normal consent sources (OneTrust C0003, analyticsConsent URL parameter, iframe src parameter), which can still grant consent on their own.

⚠️ Use only for local development and testing. This bypasses compliance controls and must never be set in production.

Sharing information with child micro applications​

LogRocket is initialized in each micro application independently. The buildLogRocketQueryParams utility lets a parent share its LogRocket configuration and consent state with child micro applications (e.g. iframes) via URL query parameters, so children inherit the right setup without hardcoding it. It also lets interoperable children work under different parents (Encompass, TPO, etc.) without changes.

The function returns the following query parameters for inclusion in the child's iframe URL:

  • analyticsConsent: 'true' if the user consented to functional cookies, else 'false'.
  • lrEnabled: 'true' if LogRocket is enabled in the parent, else 'false'.
  • lrAppId: the LogRocket application ID used by the parent.
  • lrParentOrigin: the parent's origin (e.g. https://parent-app.example.com). The child reads this to populate parentDomain for cross-origin session linking.

Important: call this after initLogRocket so the returned values reflect the parent's actual init state (the parent's consent and enabled state are captured at init time and reused here, so they stay consistent even if the user changes consent later).

import { buildLogRocketQueryParams } from '@elliemae/pui-logrocket';

const urlParams = buildLogRocketQueryParams();
// "analyticsConsent=true&lrEnabled=true&lrAppId=your-app-id&lrParentOrigin=https%3A%2F%2Fparent-app.example.com"
const childUrl = `https://child-app.example.com?${urlParams}`;
// launch guest application with childUrl using SSF V2 / App SDK GuestMicroapp

Support for Legacy AngularJS Microapps in Iframes​

For legacy AngularJS microapps running inside iframes, the library reads analyticsConsent from the iframe's src URL as a fallback so they inherit consent without code changes.

Consent Check Priority (highest to lowest):

  1. OneTrust consent groups (when OneTrust is loaded)
  2. Current window URL analyticsConsent parameter
  3. Iframe src URL analyticsConsent parameter (legacy fallback)
  4. Default: false
// No code change needed in the child microapp; the library reads it automatically.
<iframe src="https://legacy-app.com/app?analyticsConsent=true&lrAppId=my-app"></iframe>