QM Technical Training - Web Config
Created by Alex Avila
URL Blocklist - Web Capture
In Quantum Metric, blacklisted URLs refer to specific pages or endpoints that are intentionally excluded from data capture or analysis, typically for privacy, security, or noise reduction reasons. This is often used to prevent sensitive data (like login, payment, or PII-heavy pages) from being recorded in session replay or analytics.
Instrumentation Key
This key is the technical reference for this configuration item that is present in the JavaScript instrumentation. Referenced here for debugging purposes as it's not visible nor required in the UI. blacklistedURLs
| Term | Definition |
|---|---|
URL Blocklist - Web Capture | In Quantum Metric, blacklisted URLs refer to specific pages or endpoints that are intentionally excluded from data capture or analysis, typically for privacy, security, or noise reduction reasons. This is often used to prevent sensitive data (like login, payment, or PII-heavy pages) from being recorded in session replay or analytics.
Instrumentation Key
This key is the technical reference for this configuration item that is present in the JavaScript instrumentation. Referenced here for debugging purposes as it's not visible nor required in the UI. blacklistedURLs |
URL Blocklist - Example | A /checkout/payment page is blacklisted so that credit card or sensitive user input is not captured in session replay or event tracking. |
dataEncryptWhiteList | the dataEncryptWhiteList is used to define which data elements are allowed to be captured in a readable (unencrypted) format, while everything else remains encrypted by default. This ensures that sensitive data is protected while still allowing necessary fields to be analyzed for business insights. |
dataEncryptWhiteList - example | A a user enters a promo code like SPRING20 during checkout, and the field isn’t whitelisted, the value would be encrypted and unusable. By adding the promo code field to the dataEncryptWhiteList, teams can see the actual code users enter—like SPRING20—which helps debug checkout issues and analyze promotion performance, without exposing highly sensitive data. |
dataScrubRE | |
dataScrubWhiteList | defines specific elements or fields that should be excluded from scrubbing, meaning their data is allowed to remain visible even when general scrubbing rules are in place. |
dataScrubWhiteList - example | <input name="email" data-qm-allow />
Normally:
email → ❌ scrubbed (because of dataScrubRE)
But with this:
data-qm-allow → ✅ NOT scrubbed |
dataScrubXHRRegExes | dataScrubXHRRegExes is used to identify and scrub sensitive data specifically within network requests (XHR/fetch calls) before it is captured or displayed. |
dataScrubXHRRegExes vs dataScrubRE | dataScrubRE → scrubs what users see/type (UI fields)
dataScrubXHRRegExes → scrubs what gets sent behind the scenes (API/network data) |
dataScrubXHRRegExes - example | {
"email": "john@email.com",
"cardNumber": "4111111111111111"
}
👉 With dataScrubXHRRegExes:
email → ❌ scrubbed
cardNumber → ❌ scrubbed
So in QM, those values would be masked or removed. |
enableKVS | allows Quantum Metric to capture custom key-value data and attach it to user sessions, making it easier to search, filter, and analyze specific attributes.
|
enableKVS - example | A site captures:
{
"userId": "12345",
"loyaltyTier": "gold"
}
With enableKVS, you can:
Find all sessions where loyaltyTier = gold
Analyze behavior of high-value users
|
elementVeinAttributes | elementVeinAttributes is used to define which HTML attributes should be captured and associated with elements for deeper analysis. This allows teams to track additional context about user interactions beyond just clicks, such as custom data attributes tied to elements. |
elementVeinAttributes - examples | <button
id="add-to-cart-btn"
class="btn primary"
aria-label="Add Nike Air Max to cart" >
Add to Cart
</button>
👉 With this config, QM captures:
id = add-to-cart-btn
class = btn primary
aria-label = Add Nike Air Max to cart |
enableCompression | reduces the size of captured data before it’s sent, improving performance and reducing network load. |
enableWorkerCompression | reduces the size of captured data before it’s sent, improving performance and reducing network load but offloads the compression process to a web worker, so it doesn’t impact the main thread or user experience. |
Why would we use Worker Compression? | To ensure that Quantum Metric's data capture doesn't compete with our application's logic for Main Thread resources, specifically to keep our INP scores low. |
What happens if both are off? (enableCompression & enableWorkerCompression) | - Payloads become much larger
- increasing the risk of network congestion and
- potential data loss if the user navigates away before a large uncompressed beacon finishes sending. |
encryptScrubList | encryptScrubList defines specific elements or fields whose data should always be encrypted. Is an array of CSS selectors (IDs, classes, or attributes) that tells the Quantum Metric tag: "Do not block this data, but do not send it in plain text either. Encrypt it on the client side before it leaves the browser." |
What happens if an element is identified in both the dataScrubWhiteList and the encryptScrubList? | Usually, Encryption wins or they coexist. You are saying "I want this data (Whitelist), but it must be protected (Encrypt)." The data will be captured, but in its encrypted state. |
How does the use of dataScrubRE impact browser performance compared to the other two? | How does the use of dataScrubRE impact browser performance compared to the other two?" |
excludeDOMList | excludeDOMList is used to completely exclude specific elements or sections of the DOM from being captured.
This means those parts of the page are not recorded at all in session replay or data collection. It’s typically used for privacy, security, or to remove irrelevant/noisy content. |
Why would we choose excludeDOMList over encryptScrubList for a sensitive form? | If we don't need any analytics from that form and want to eliminate 100% of the risk and 100% of the CPU processing time for that section. |
forceElementCSSInline | forceElementCSSInline forces CSS styles to added directly into captured replay data instead of being loaded separately.
It’s typically used when a site has highly dynamic or changing styles that can cause replay issues. This helps ensure session replays render correctly and consistently.
|
Can forceElementCSSInline help if the client's images are missing in the replay? | No. This setting only affects CSS properties (colors, dimensions, fonts). If images are missing, that is usually a Base URL or asset hosting issue. |
In plain English, what does forceElementCSSInline actually do? | It takes the "style" of a specific part of the page and "pins" it directly onto the element so Quantum Metric doesn't lose it during the recording. |
forceElementCSSUpload | If you add a selector to forceElementCSSUpload, Quantum Metric will physically grab the CSS file associated with that element and upload a copy of it to Quantum Metric's own secure servers.
|
Does forceElementCSSUpload upload the actual HTML of the page? | No.
It only uploads the CSS files (stylesheets). The HTML is captured separately through the standard DOM capture process. |
Can we 'force' an upload manually, or is it always automatic based on the list? | It is automatic. Once the selector is in the configuration, the tag waits for a user to visit a page with that element and then triggers the upload. |
hashUploadURL | hashUploadURL is the base URL used by the Resource Loader to store and serve cached resources, especially CSS needed for replay rendering.
The general idea is that QM can cache stylesheet rules on its own server, and then replay loads those cached versions instead of depending on the original hosted files. This helps make replay rendering more stable and consistent.
|
hashUploadURL - example | If a site has:
hashUploadURL: "https://rl.quantummetric.com/lululemon"
👉 That means QM’s Resource Loader is using that base URL to serve the cached stylesheet resources for replay.
So instead of replay trying to pull CSS from the client’s live site every time, it can use the cached QM-hosted version from that hashUploadURL path. |
"In simple terms, what is a 'Hash' in this context?" (hashUploadURL) | it’s a unique "fingerprint" for a URL that helps Quantum Metric organize and find saved files quickly. |
Is hashUploadURL turned on by default? | Usually, yes. It is a standard "best practice" for storage efficiency in 2026. |
If a replay is showing an OLD version of our header, could this setting be involved? (hashUploadURL) | Yes. It means QM is likely "caching" the old file based on a hash that hasn't updated yet. |
hashUploadPercent | hashUploadPercent controls the percentage of sessions for which resources (like CSS) are uploaded and cached for replay.
- It’s used to limit how often this process happens,
- helping balance replay quality with performance
- it samples a portion.
|
hashUploadPercent
"What does this setting actually control? | It controls the frequency or probability that a user's browser will upload a website asset to Quantum Metric. |
hashUploadPercent
How does this setting interact with forceElementCSSUpload? | They work together.
forceElement... says WHAT to upload;
hashUploadPercent says HOW OFTEN to try. |
ignoreAttributes | ignoreAttributes defines which HTML attributes should not be captured at all when collecting element data. |
Is it better to 'Scrub' an attribute or 'Ignore' it? | Ignore is safer. Scrubbing might leave the "shape" of the data visible, while Ignoring removes the possibility of it being captured entirely. |
How do I test if an attribute is actually being ignored? | Check the Network Tab in your browser. Look at the "Mutation" data being sent by the QM tag. If the attribute you ignored isn't in the code snippet being sent, it's working. |
ignoreElementCSSSerialization
what is Serialization? | "Serialization" is. In Quantum Metric, serialization is the process of taking the complex, "live" CSS styles in the browser and turning them into a text format that can be sent over the internet. |
What is the main benefit of using ignoreElementCSSSerialization?
| It reduces the CPU load on the user's browser, helping to keep the site fast and responsive (improving INP scores). |
logResourcePercent | logResourcePercent controls the percentage of sessions where resource data (like CSS, images, or other assets) is logged and captured. It’s used to limit how much resource data is collected, helping balance visibility with performance and data volume. Instead of logging resources for every session, it samples a subset.
|
What is logResourcePercent? | Every time a website loads an image, a script, or a font, that is a "resource." Quantum Metric can record these in the "Network" tab of the session replay so analysts can see if a specific image failed to load or if a script was too slow. |
logResourcePercent
"If I set this to 10%, what happens?" | only 10 out of every 100 sessions will have data in the "Resources" section of the Network tab. The other 9 will have empty resource logs. |
logResourcePercent
"Does this setting help fix broken styles in a replay?" | It doesn't fix them, but it helps you diagnose them. It shows you if the CSS file failed to load (e.g., a 500 server error). |
Why might Korean Air choose to keep this at 0%? | Likely for extreme performance or data minimization. By not logging resources, they reduce the "chatter" (metadata) sent from the user's phone or computer to the cloud. |
Why would Gucci want this at 100%? | Gucci likely prioritizes technical perfection.
If a luxury image fails to load or is slow, they want to know exactly which file it was for every customer. |
allowedResourceTypes | allowedResourceTypes defines which types of resources (like CSS, images, scripts, etc.) are allowed to be captured when resource logging is enabled.
It helps control what gets included in resource data to reduce noise and focus on what’s actually useful. |
maskInputs | maskInputs controls whether user input fields are masked so that typed values are not visible in session replay or data capture.
When enabled, sensitive information entered by users (like form inputs) is hidden by default. This helps protect user privacy and ensures compliance. |
maskInputs
Why would it be set to false? | If maskInputs is false, it means Quantum Metric is not automatically masking every single box. |
If maskInputs is false, what stops us from accidentally capturing a customer's Credit Card number? | QM relies on dataScrubRE (pattern matching) to catch the number regardless of which box it's typed in, or we have tagged that specific Credit Card field with a 'Mask' class in our HTML. |
If we find PII in a replay, and this is set to false, what is the first thing we should do? | Create a dataScrubRE for that specific data immediately |
maskSensitiveQueryParams | maskSensitiveQueryParams ensures that sensitive values in URL query parameters are masked so they are not visible in captured data or session replay. It protects data that appears in URLs, such as tokens, emails, or IDs. This helps prevent exposure of sensitive information passed through query strings. |
maskSensitiveQueryParams - example | 💡 Example
A user lands on a URL like:
https://example.com/checkout?email=john@email.com&token=abc123
👉 With maskSensitiveQueryParams:
email → ❌ masked
token → ❌ masked
So QM would show something like:
https://example.com/checkout?email=****&token=****
|
maskSensitiveQueryParams
What is the performance risk of Lululemon’s list of 64 items? | Every time a user navigates to a new page, the Quantum Metric tag has to scan the URL for all 64 keys. While modern browsers are fast, a list this long adds a tiny bit of "regex/loop" overhead to every page load. |
maskSensitiveQueryParams
homedepot has only 6 items | "We know exactly where our PII is. We only mask the specific keys we use." |
maxSessionDuration | maxSessionDuration defines the maximum amount of time a single user session can last before it is automatically ended.
This ensures sessions don’t run indefinitely and helps keep session data manageable and consistent. After the limit is reached, a new session will start.
|
What is the literal effect of maxSessionDuration: 0 on a session replay? |
It prevents the session from being forcefully "restarted" by a timer. |
Why would a site like Home Depot or Lululemon choose 0? | To ensure that if a customer is doing a "deep dive" project (like designing a kitchen or building a large cart), the journey isn't fragmented. |
maxSyncSize | Quantum Metric doesn't send data in one giant file at the end of a session. Instead, it "batches" data into small packets and sends them periodically (this is called "syncing").
The Setting: maxSyncSize defines the maximum payload size (usually in bytes) for a single data "batch" being sent from the browser to Quantum Metric's servers. |
maxXHRDataLength | defines the maximum amount of data captured from XHR or fetch requests
|
maxXHRDataLength - explain how it works | When your website talks to a server (to check a price, log in a user, or fetch a product list), it uses XHR or Fetch calls. These calls send and receive "JSON" data.
The Setting: This defines the maximum number of characters (bytes) of the API response that Quantum Metric will record.
If the API response is smaller than this limit: The whole response is captured.
If the API response is larger: Quantum Metric "truncates" (cuts off) the data at this limit to save space. |
maxXHRDataLength
Why would Lululemon have a limit that is 10x higher than Home Depot's? | Lululemon’s site might rely on very large JSON responses for their product grids, store availability, or personalized recommendations. 20KB might not be enough to see the whole "conversation" between the browser and the server. |
percentSampling | controls the percentage of user sessions that are captured and recorded.
This setting determines the percentage of total website visitors that will be captured by Quantum Metric.
The Setting: A number between 0 and 100.
The Logic: If set to 50, every second person who visits the site gets a cookie, their session is recorded, and data is sent. The other 50% of users see the site normally, but the Quantum Metric tag remains "dormant" and sends nothing. |
What is the risk of a very low sampling rate (e.g., 1%) | You might miss "Edge Case" bugs that only happen to a few people. It’s also harder to find a specific session if a customer calls support with a complaint. |
Can we sample based on 'Device Type' (e.g., 100% on Mobile, 50% on Desktop)? | Yes, using advanced configuration logic, you can prioritize certain devices or regions. |
publicKeyString | allows for Client-Side Encryption. It ensures that the client remains the 'Owner' of their sensitive data by encrypting it before it ever reaches the cloud.
This provides a 'Zero-Trust' environment where PII is searchable but never exposed in plain text. |
In simple terms, what does this publicKeyString represent? | It is the Public Key part of an encryption pair that allows the browser to "lock" data before sending it to the cloud. |
Where does the encryption actually happen? | On the user's device (the browser). The data is encrypted before it is sent over the network. |
queryParamForSessionId | Quantum Metric generates its own random ID for a session. However, sometimes a client wants to "force" a specific ID so they can match a session to another system (like a marketing email or a customer support ticket).
|
queryParamForSessionId
Can we use this to find a session in the Quantum Metric search bar? | Yes. This is the main benefit. You can search for the "External ID" and the matching session will pop up. |
queryParamForSessionId
Why would a developer prefer this over the standard QM Session ID? | Because they already have their own IDs in their database (SQL/NoSQL) and they want a "bridge" between their data and Quantum Metric’s visual replays. |
queryParamForUserId | tells QM to read a user identifier from a URL query parameter. It can be used to associate sessions or behavior with a known user ID when that value is passed in the URL. |
replaceURLRegExes | is used to modify parts of URLs by matching patterns and replacing them with a different value. This helps, remove dynamic or sensitive values, and improve data consistency. It’s commonly used to make analytics cleaner and easier to group. |
replayEnabled | determines whether session replay is captured and available. If enabled, user sessions can be visually replayed to see interactions and behavior. If disabled, no replay data is recorded, even though other analytics may still function. |
reportURL | This configuration defines the endpoint where Quantum Metric sends captured session and interaction data, ensuring it’s routed to the correct environment for processing. |