Customization

• 1: Data Element Auto Selection
• 2: Page Content Processing
• 2.1: Protegrity Standard Attribute
• 2.2: Custom Mapping Configuration
• 2.2.1: Domain Matching Rules
• 2.2.2: Sibling Match Criteria
• 2.2.3: Table Column Unprotection
• 2.3: Stored Suggestions

1 - Data Element Auto Selection

Data Element Auto Selection Feature

What It Does

When a user selects an element on a page and opens the extension popup, the extension checks if it has a stored record for that element. If a match is found, the data element and operation dropdowns are pre-selected automatically. This saves the user from manually choosing the same values on repeat visits.

When Data Element Auto-Selection Occurs

The extension runs the SuggestionMatcher every time a user selects an element and the popup opens. It checks the following in order:

1. data-pty-dataelement attribute — If the element has this HTML attribute and its value matches a configured data element, that data element is pre-selected immediately.

2. Custom mapping — If a custom mapping config exists and the current domain + element matches an admin-defined rule, the mapped data element and operation are pre-selected.

3. Stored suggestions — If neither of the above applies:

   • The current page URL is compared against previously stored documents.
   • If the URL matches, the current element is compared against stored suggestions for that document using weighted scoring (id, xpath, custom attributes, table column name, context xpaths).
   • An exact match or a score above the confidence threshold (default 0.5) results in pre-selection of the stored data element and operation. Among multiple matches, the one with the highest match_frequency wins.

If nothing matches, the dropdowns remain empty and the user selects manually.

When a Suggestion Gets Saved

After the user completes a protect or unprotect operation:

• If the element matched an existing suggestion and the user kept the same data element, the suggestion’s match_frequency is incremented.
• If the element matched but the user chose a different data element, the suggestion is updated accordingly.
• If no match existed, a new suggestion is saved with the element’s identifying properties, the chosen data element, and operation.

Relationship to “Process Page Content” Settings

The popup settings Process Page Content Automatically and Process Page Content based on past usage are unrelated to data element auto-selection. Those settings control whether the extension automatically processes elements on page load without user interaction.

If a user has processed the same data on the page 3 or more times, if they have the “Process Page Content based on past usage” turned ON, that data will be automatically processed.

Meaning this feature won’t be able to be used for those pieces of data, but any data that has been processed by the user but has not been processed atleast 3 times, will still have its data element and operation auto selected.

2 - Page Content Processing

Page Content Processing

When the Browser Protector scans a page, it evaluates each element against a three-tier detection pipeline. Steps are executed in priority order — once an element is processed by an earlier step, it is marked and skipped by all subsequent steps.

1. Protegrity Standard Attribute

The highest priority. Any element carrying the data-pty-dataelement attribute is processed first, unconditionally. This path requires no configuration beyond the attribute being present in the page’s HTML and is the most reliable and explicit method of identifying protected elements.

2. Custom Mapping Configuration

If no standard attribute is found, the extension checks whether the element matches any admin-preconfigured custom mapping rules for the current domain and page. Custom mappings target elements by their HTML attributes, values, and optionally by their position in the DOM hierarchy. This path is appropriate when the web application cannot be instrumented with Protegrity attributes but the page structure is well understood.

3. Stored Data from previous unprotections

The lowest priority, and only active when Unprotect Based on Past Usage is enabled in the application settings. The extension checks whether the element’s location matches a previously saved user-confirmed mapping that has exceeded the required match frequency threshold. This path requires no upfront configuration and builds its knowledge from user interactions over time.

2.1 - Protegrity Standard Attribute

Protegrity Standard Attribute

The Protegrity Standard Attribute is the most direct way to instruct the Browser Protector to unprotect a specific element on any web page. When an HTML element is annotated with the data-pty-dataelement attribute.

This approach is intended for use when the web application itself can be instrumented — for example, when the application’s front-end templates or server-rendered HTML can be modified to include Protegrity markup.

How It Works

Add the data-pty-dataelement attribute to any HTML element that contains a protected value. Set the attribute’s value to the name of the Protegrity data element that was used to protect the data.

<span data-pty-dataelement="SSN">***-**-1234</span>

When the extension runs (either on page load or on DOM change), it scans the page for all elements carrying this attribute and submits each element’s text content to the Protegrity service for unprotection using the specified data element. The element’s text content is then replaced in-place with the plaintext result.

Processing Behavior

• The attribute value matching against configured data elements is case-insensitive.
• Elements that have already been processed are marked with a data-pty-processed attribute to prevent duplicate API calls.
• Elements with an empty data-pty-dataelement value or no text content are skipped.
• If the attribute value does not match any data element configured in the extension, the element is skipped with a warning logged to the browser console.
• When Unprotect Automatically is enabled, the extension also monitors the DOM for newly added elements carrying this attribute (e.g. content loaded dynamically after page load).

Priority

Standard attribute processing runs first, before custom mapping rules. This means any element tagged with data-pty-dataelement will always be processed by the standard attribute path, regardless of whether a custom mapping also matches it.

Example

Given the following rendered HTML:

<td data-pty-dataelement="FullName">John Doe token here</td>
<td data-pty-dataelement="SSN">***-**-6789</td>

The extension will submit both elements to the unprotection service — one using the FullName data element and one using SSN — and replace their contents with the corresponding plaintext values.

2.2 - Custom Mapping Configuration

Custom Mapping Configuration

Custom mappings allow administrators to explicitly tell the Browser Protector which HTML elements on a specific site need to be protected or unprotected.

Custom mappings are defined under the optional customMappings key in the extension configuration JSON.

Structure Overview

customMappings
└── domains[]
    ├── domain                          — hostname to scope the rules to
    ├── page[]
    │   ├── path[]                      — URL path segments to scope rules to (empty = all paths on the domain)
    │   └── mappings[]                  — groups of attribute-based rules
    │       ├── attributeName           — HTML attribute to inspect (e.g. id, class, aria-label)
    │       ├── value                   — expected attribute value; omit to match on attribute presence alone
    │       └── entries[]
    │           ├── dataElement         — Protegrity data element name to use for the operation
    │           ├── operation           — "protect" or "unprotect"
    │           ├── splitSegments       — (optional) split text content into individual tokens before processing
    │           └── parentConditions[]  — (optional) ancestor element constraints for narrowing matches
    └── title[]
        ├── path[]                      — URL path segments to scope title rules to (empty = all paths on the domain)
        └── algo                        — identifier for the page title unprotection algorithm to use

Domain Matching

Exact domain entries take precedence over wildcard entries.

To read more about domain rules, go here.

Path Matching

• An empty path array applies the mapping rules to every page on the matched domain.
• When paths are provided, they are matched as substrings of the current URL path (e.g. "/accounts" matches /accounts/list).

Parent Conditions

parentConditions can optionally restrict a mapping so it only fires when the target element has a specific ancestor within a certain number of DOM levels. Each condition can check the ancestor’s tag name, an attribute name, and/or an attribute value.

Example

The following configuration unprotects any element on crm.example.com that has aria-label="customer-ssn", using the SSN data element:

"customMappings": {
    "domains": [
        {
        "domain": "crm.example.com",
        "page": [
            {
            "path": [],
            "mappings": [
                {
                "attributeName": "aria-label",
                "value": "customer-ssn",
                "entries": [
                    {
                    "dataElement": "SSN",
                    "operation": "unprotect"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

When the extension detects an element such as:

<span aria-label="customer-ssn">***-**-1234</span>

This example html element will match the custom mapping rule above, allowing the Protegrity browser protector to know this is an element that when selected, will use the SSN data element for unprotection.

Page Title Unprotection

The title array within a domain entry enables unprotection of protected values embedded in the browser’s page <title>. This is useful for single-page applications (such as Salesforce) that reflect record data in the tab title after navigation.

Each title entry specifies:

• path — URL path scope (empty array = applies to all pages on the domain)
• algo — the name of the page title extraction algorithm to use

The extension monitors the <title> element for changes and re-runs unprotection on navigation or if the title changes.

Example

"customMappings": {
  "domains": [
    {
      "domain": "myorg.example.com",
      "title": [
        {
          "path": ["/example/r/User"],
          "algo": "Example_Algo"
        }
      ]
    }
  ]
}

For a title such as example Title, the extension will unprotect and rewrite the title with the plaintext result.

Notes

• Attribute matching is case-insensitive.
• Class attribute matching supports partial class list matching (i.e. the configured value only needs to appear as one class in a multi-class attribute).

2.2.1 - Domain Matching Rules

Exact Match Rules (config does NOT start with *)

Config: example.com

Config: www.example.com

Config: hr.example.com

Wildcard Rules (config starts with *)

Both *example.com and *.example.com normalize to base example.com.

Config: *example.com or *.example.com

Exact vs. Wildcard Priority

When both example.com (exact) and *.example.com (wildcard) are in config, exact entries are evaluated first. Wildcard is only used as a fallback.

Things That NEVER Affect Matching

2.2.2 - Sibling Match Criteria

Overview

Sibling matching is configured through siblingMatchCriteria on a mapping entry. It is a context filter: your primary mapping still finds candidate elements, and siblingMatchCriteria decides whether each candidate should be unprotected based on what appears near it.

Use it when:

• The same target element pattern appears in multiple places on a page
• Only one section should be unprotected
• A nearby label or marker identifies the correct context

How to Think About It

Treat it as an “anchor” check:

1. The mapping finds a candidate target element.
2. The feature looks around that target for a nearby element that matches your criteria.
3. If a match is found, the target is unprotected.
4. If no match is found, that target is skipped.

This keeps rules precise without requiring fragile or overly specific selectors.

siblingMatchCriteria Fields

• labelText (optional) — Text that should appear on the nearby anchor element.
• elementType (optional) — Expected tag name of the anchor element (for example, label, div, span).
• attributeName (optional) — Attribute that must exist on the anchor element.
• attributeValue (optional) — Optional expected value for attributeName.
• direction (optional) — Where to look relative to the target (left or right).
• distance (optional) — How far the search can expand through nearby structure.

If you provide multiple fields, they are treated as one combined match. In other words, the same nearby element must satisfy all specified criteria.

HTML Matching Example

Example target and nearby context:

<div class="field-row">
  <div title="Account Name">Account Name</div>
  <a data-special-link="true">PTY:93f2a1...</a>
</div>

Example mapping entry:

{
  "targetElement": "a",
  "attributeName": "data-special-link",
  "attributeValue": "true",
  "entries": [
    {
      "dataElement": "deName",
      "operation": "unprotect",
      "siblingMatchCriteria": {
        "labelText": "Account Name",
        "elementType": "div",
        "attributeName": "title",
        "attributeValue": "Account Name",
        "direction": "left",
        "distance": 2
      }
    }
  ]
}

In this example, the link is only unprotected when the matching context element (<div title="Account Name">) is present on the left. The same a[data-special-link="true"] elsewhere on the page will be skipped if that context is missing.

Additional Example: Right-Side Match

<div class="field-row">
  <span class="value" data-tokenized="true">PTY:0ab123...</span>
  <span data-role="field-label">Phone</span>
</div>

{
  "targetElement": "span",
  "attributeName": "data-tokenized",
  "attributeValue": "true",
  "entries": [
    {
      "dataElement": "dePhone",
      "operation": "unprotect",
      "siblingMatchCriteria": {
        "labelText": "Phone",
        "attributeName": "data-role",
        "attributeValue": "field-label",
        "direction": "right"
      }
    }
  ]
}

This configuration only unprotects tokenized values when the matching “Phone” label is found to the right.

2.2.3 - Table Column Unprotection

Overview

The Table Column Unprotection feature allows you to target entire table columns using columnMatchCriteria on a mapping entry. Rather than creating selector-based rules that match individual cells row by row, you define a single column mapping that identifies the column by its header label and automatically unprotects all qualifying data cells beneath it.

This is ideal for:

• Protecting sensitive columns in data tables (email, phone, SSN, etc.)
• Avoiding repetitive selector rules when the same column appears across multiple page layouts
• Working with component-based tables (e.g., Salesforce Lightning) where cell markup is complex and nested

How It Works: From Configuration to Unprotection

When a mapping entry includes columnMatchCriteria, the unprotection process follows these steps:

1. Locate the column — The feature searches the page for <table> elements and finds the target column by matching its header text against columnLabel.

2. Collect data cells — Once the column is identified, all <td> elements in that column are gathered, along with any <th scope="row"> elements (used by component-based tables to mark per-row headers like “Account Name” or “Contact ID”).

3. Extract values and unprotect — For each data cell, the feature locates the actual value text (which may be wrapped in nested elements) and sends it for unprotection. The feature intelligently skips visually-hidden helper markup (like “Edit” buttons or sorting labels) to ensure only intended values are unprotected.

4. Apply filters (optional) — If you’ve specified an attributeName and attributeValue, unprotection only occurs if the target element (table, cell, or header) carries that attribute.

Configuration: columnMatchCriteria

A column mapping entry uses the columnMatchCriteria object to specify which column to unprotect:

• columnLabel (required, string) — The visible text of the column header. Matching is case-insensitive and punctuation-tolerant (e.g., “Email Address:” matches configured "email address"). The feature searches the table’s header region (<thead> or leading <th> rows) for a header whose text normalizes to this value.

• columnNumber (optional, number, 1-based) — A performance hint: the logical position of the column (e.g., columnNumber: 3 for the third column). When provided, the feature checks this column position first. If the header at that position doesn’t match columnLabel, the feature automatically falls back to a full-column search. This lets you optimize for tables with known column orders while remaining robust to layout changes.

Filtering with Attributes

Like selector-based mappings, you can use attributeName and attributeValue to narrow down which tables or cells are processed:

• targetElement — Specifies what to check for the attribute:

  • "table" — Check the <table> element itself; only process columns in tables carrying the attribute.
  • "th" — Check the header cell; only process if the column header carries the attribute.
  • "td" (or empty) — Check data cells; only process if at least one data cell in the column carries the attribute.

• attributeName and attributeValue — Standard attribute filtering. If attributeName is omitted or empty, no filtering is applied.

Example: If you set targetElement: "table" and attributeName: "data-pii-table", column unprotection only runs on tables marked with data-pii-table.

Handling Multi-Token Values

If a cell contains space-separated values (e.g., “John Doe” or “Open - NotContacted”), use splitSegments: true to unprotect each token individually. This is necessary when your unprotection service requires single-token inputs.

{
  "columnMatchCriteria": {
    "columnLabel": "Full Name"
  },
  "splitSegments": true
}

Column Identification Robustness

The feature handles various header and cell markup patterns:

• Wrapped headers — Headers with nested elements (<th><span>Email</span></th>) are recognized by their visible text content.
• Merged headers — Tables with colspan/rowspan are supported; columns are correctly identified even when headers or data cells span multiple logical positions.
• Component markup — Salesforce Lightning, custom Web Components, and other complex nested layouts work correctly because the feature targets the actual value node, not the container.
• Hidden helper text — Helper elements (like “Edit X” button labels or sort indicators) are automatically excluded from unprotection.

Idempotency and Precedence

• Idempotency — If a cell is already marked as unprotected (via a previous rule or pass), it is skipped. This prevents redundant unprotection and allows you to layer multiple mapping strategies without conflicts.

• Precedence — Column mappings are applied after selector/attribute mappings. This two-phase approach ensures that targeted, specific rules (e.g., a particular field with a unique attribute) take priority, and column mappings only unprotect cells that haven’t already been claimed.

Limitations

• Requires real HTML tables — Only <table> markup is supported. Tables built from <div> or other grid elements are not detected.
• Separate header and data tables — If a page renders headers and data in separate <table> elements (e.g., sticky headers), the feature may not find the data cells. In such cases, use selector-based mappings as a fallback.
• Single column per mapping — Each columnMatchCriteria identifies one column. If you need to unprotect multiple columns, create multiple mapping entries.

Example Configurations

HTML Matching Examples

Example A: Match by header label

<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th>Status</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Jane Doe</td>
      <td>PTY:a82b9...</td>
      <td>Active</td>
    </tr>
  </tbody>
</table>

{
  "entries": [
    {
      "dataElement": "deEmail",
      "operation": "unprotect",
      "columnMatchCriteria": {
        "columnLabel": "Email"
      }
    }
  ]
}

This configuration unprotects values in the Email column across matched tables.

Example B: Match only tables with an attribute

<table data-pii-table="true">
  <thead>
    <tr>
      <th>Employee</th>
      <th>SSN</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alex Smith</td>
      <td>PTY:9e13f...</td>
    </tr>
  </tbody>
</table>

<table>
  <thead>
    <tr>
      <th>Employee</th>
      <th>SSN</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Sam Lee</td>
      <td>PTY:0a44c...</td>
    </tr>
  </tbody>
</table>

{
  "targetElement": "table",
  "attributeName": "data-pii-table",
  "attributeValue": "true",
  "entries": [
    {
      "dataElement": "deSSN",
      "operation": "unprotect",
      "columnMatchCriteria": {
        "columnLabel": "SSN"
      }
    }
  ]
}

Only the first table is processed because it matches the table-level attribute criteria.

Simple: Unprotect the “Email” column

{
  "targetElement": "th",
  "attributeName": "",
  "entries": [
    {
      "dataElement": "deEmail",
      "operation": "unprotect",
      "columnMatchCriteria": {
        "columnLabel": "Email"
      }
    }
  ]
}

With fast path hint: Unprotect “Phone” at column 2, fallback to search if mismatch

{
  "entries": [
    {
      "dataElement": "dePhone",
      "operation": "unprotect",
      "columnMatchCriteria": {
        "columnLabel": "Phone",
        "columnNumber": 2
      }
    }
  ]
}

Filtered: Unprotect “SSN” only in PII tables

{
  "targetElement": "table",
  "attributeName": "data-pii-table",
  "entries": [
    {
      "dataElement": "deSSN",
      "operation": "unprotect",
      "columnMatchCriteria": {
        "columnLabel": "SSN"
      }
    }
  ]
}

Split tokens: Unprotect “Full Name” with token separation

{
  "entries": [
    {
      "dataElement": "deName",
      "operation": "unprotect",
      "splitSegments": true,
      "columnMatchCriteria": {
        "columnLabel": "Full Name"
      }
    }
  ]
}

2.3 - Stored Suggestions

Stored Suggestions

Stored suggestions are the extension’s memory of past user-confirmed unprotection actions. When a user manually unprotects an element through the extension, that element’s location and data element mapping are saved locally. On subsequent visits to the same page, the extension can automatically re-apply those unprotections without any further user interaction — provided the Unprotect Based on Past Usage setting is enabled.

How Suggestions Are Created

Each time a user performs a manual unprotect operation on an element, the extension records a suggestion containing:

• The element’s XPath and positional offsets within the DOM
• Contextual XPaths of the surrounding elements (preceding sibling, following sibling, parent)
• The element’s id, class, attributes, and any custom attributes
• The data element and operation type selected by the user
• A match_frequency counter, starting at 1

Suggestions are stored in Chrome’s local storage (device-local, not synced across browsers) and are scoped per URL — organised by domain, path segments, query parameters, and hash.

Match Frequency

Every time a suggestion is confirmed again on the same element, its match_frequency counter is incremented. This counter acts as a confidence signal: the more times a particular mapping has been confirmed by the user, the more reliably it can be applied automatically.

When Unprotect Based on Past Usage runs on page load, only suggestions whose match_frequency exceeds the configured frequencyResetThreshold are applied automatically.

A suggestion with match_frequency of 1 will not be applied automatically at the default threshold — it must be confirmed at least twice before it is trusted for automatic unprotection.

How Automatic Re-application Works

When the page loads and Unprotect Based on Past Usage is enabled, the extension:

1. Looks up stored suggestions for the current URL
2. Filters to only those exceeding the frequency threshold
3. Resolves each suggestion’s XPath against the current DOM
4. Submits the matched element’s content to the Protegrity service for unprotection using the stored data element

Stored suggestion unprotection runs after standard attribute and custom mapping unprotection in the processing order. Elements already processed by an earlier step are skipped.

Storage Scope

Suggestions are stored in chrome.storage.local — they are local to the device and browser profile they were created on. They are not synced via Chrome’s sync storage and are not shared across devices or user profiles.