Site owners: public widget API and advanced masking

Use window.OmnifoxCobrowse.mask() and the data-rrweb-mask attribute to hide bespoke sensitive fields during co-browse.

Jun 26, 2026

Watch this step in the video · What the customer types stays hidden

What it is and when you need it

Omnifox co-browse masks passwords and card data by default before the agent sees anything. But if your site has bespoke sensitive fields (a custom payment component, an ID input built from a <div contenteditable>, a non-standard widget), the automatic detector may not recognize them. For those cases the widget exposes a public API on window.OmnifoxCobrowse, aimed at site owners.

Important: masking runs in the customer's browser, before the DOM is sent. A masked field never reaches the agent.

Requirements

  • The Co-browse add-on active on your organization (Billing → Co-browse).
  • The Webchat widget installed on your site (the cobrowse.js bundle loads on demand when a session starts).

The public API

While a session is active, window.OmnifoxCobrowse offers:

  1. OmnifoxCobrowse.mask(selectorOrElement) — marks an element (or every match of a CSS selector) as masked. Returns how many elements it tagged.
  2. OmnifoxCobrowse.getState() — returns the current state (idle, awaiting_consent, connecting, streaming, ended). Handy for debugging.
  3. OmnifoxCobrowse.start(params) / OmnifoxCobrowse.end(reason?) — used internally by the widget; you normally don't call these.

Steps to mask your own fields

  1. Find the CSS selector of your sensitive field (e.g. #custom-card or .cvv-input).
  2. Call the API once the field exists in the DOM:
if (window.OmnifoxCobrowse) {
  window.OmnifoxCobrowse.mask('#custom-card');
  window.OmnifoxCobrowse.mask('.cvv-input');
}
  1. If your app is a SPA and the field appears later, call mask() again after it renders. The call is idempotent — masking twice is harmless.

No-code alternative: the data-rrweb-mask attribute

If you'd rather not touch JavaScript, add data-rrweb-mask="true" straight to the element's HTML. It hides both the typed value and the rendered text (ideal for a <span> showing an already-loaded card number). The widget honors that attribute, and the automatic detector tags fields with the very same one.

Verification

  1. Start a test session from the Inbox (the Start co-browsing button).
  2. In the agent view, type into your custom fields: they should appear as a redacted block, not the real content.
  3. In the customer's browser console, window.OmnifoxCobrowse.getState() should return streaming.

If it doesn't work

  • window.OmnifoxCobrowse is undefined: the bundle hasn't loaded yet. It only exists during a session — wrap your calls in if (window.OmnifoxCobrowse).
  • The field is still visible: check that the selector matches (test with document.querySelectorAll('#your-selector')). If the element is recreated, re-apply mask().
  • You want to hide a whole container: mask the container; masking applies to the rendered subtree.

Tips

  • Third-party payment forms embedded in an <iframe> are not transmitted at all, so they're already protected.
  • Combine the API with keywords: naming inputs with terms like card or cvv lets the detector hide them on its own.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp