Cobrowse

@investec/plugins-cobrowse wraps the Cobrowse.io Web SDK behind a small, lazy-loaded lifecycle. It deliberately does not accept Investec cookies, access tokens, capabilities, AuthResponse data, or Invsy state.

Package

npm install --save @investec/plugins-cobrowse

Parent shell controller

The authenticated shell supplies the licence and policy. The plugin controller owns SDK lifecycle, session codes, iframe bridge orchestration, and shared session state:

import { CobrowsePlatformController } from '@investec/plugins-cobrowse';

const cobrowse = new CobrowsePlatformController({
  license: import.meta.env.VITE_COBROWSE_LICENSE_KEY,
  isEnabled: () => featureToggleEnabled,
  isAuthorized: () => loggedIn && permittedClientType,
  getFrames: () => Array.from(document.querySelectorAll('web-core iframe')),
  getTrustedOrigins: () => approvedFeatureOrigins,
  isApprovedOrigin: isApprovedInvestecOrigin,
  getCustomData: () => ({ user_id: authenticatedZetaId }),
  parentConfiguration: {
    registration: false,
    privateByDefault: true,
    unredactedViews: ['#sideloadCenter', '#cobrowseSessionDialog'],
  },
});

const code = await cobrowse.createSessionCode();

Generate the code only after the authenticated customer chooses to start a session. The plugin follows the Web SDK order of client(), start(), then createSessionCode(). Six-digit codes expire after approximately 20 minutes, and the SDK must not be used as a platform keep-alive.

The plugin does not import platform environment variables, authentication state, feature state, or routing. Those values are passed through callbacks so the package remains independent of the host platform implementation.

allowIFrameStart is available for standalone integrations that intentionally run inside an iframe. allowHeadless exists only to support automated plugin verification and must remain disabled in production platform configuration.

customData is passed to Cobrowse before startup so permitted identifiers can be searched in the agent dashboard. Investec Online supplies only the authenticated Zeta ID as user_id. Never send an authentication token, cookie, capability payload, ID number, bank account number, email address, or another unnecessary customer attribute.

Cross-origin feature frame

Cobrowse requires its SDK in both sides of a cross-document iframe. The child does not receive or configure the licence. On Investec Online this bootstrap is owned by the shared Invsy SDK and activated by the platform shell; consumer applications must not duplicate this lifecycle code. The equivalent internal configuration is:

const bridge = new InvestecCobrowse();

bridge.configure({
  mode: 'child',
  trustedOrigins: [approvedParentOrigin],
  registration: false,
  privateByDefault: false,
});

await bridge.start();

Only origins that have passed the shared platform's Investec-host validation may be trusted. Do not use an arbitrary document.referrer origin without validation.

Redaction contract

The parent shell is private by default:

• body is redacted before the SDK starts;
• only elements explicitly reviewed and marked [data-cobrowse-visible] are visible;
• consumers may add narrow unredaction selectors for reviewed, non-sensitive UI;
• the plugin's baseline input, balance, account-number, IBAN, [data-cobrowse-redacted], and [data-cobrowse-private] selectors remain redacted even inside an allowed application surface.

Consumer frames and the standalone plugins demo use block-list mode. Existing content remains visible while the baseline selectors and explicit privacy markers remain redacted.

Anything unredacted must be reviewed for PII, balances, account/card/IBAN numbers, transactions, notifications, documents, QR codes, and authentication data. Dynamic overlays and portal-rendered DOM are part of the same review.

Session and auth boundary

• Start only from a valid authenticated platform state.
• End and stop on logout, invalid session, or transition into an excluded journey.
• Never start on login, MFA, password, security-question, or recovery screens.
• Supply only the approved Zeta ID as Cobrowse user_id; never derive an identifier from rcv_ias, another cookie, or a capability payload.
• Starting Cobrowse cannot elevate a PIN session, call the session service, or extend bank-session inactivity.

Licence configuration

The Web SDK licence is build-time browser configuration. Inject it through the consumer's environment-specific deployment configuration as VITE_COBROWSE_LICENSE_KEY; do not store it in Wrangler session variables, cookies, local storage, capabilities, or source-controlled production values.

Extension boundary

The plugin owns SDK loading, lifecycle, session-code creation, event state, iframe bridge orchestration, protocol constants, and redaction configuration. The shell owns authentication eligibility, the licence, approved-origin discovery, presentation, and analytics. Invsy owns the child bootstrap, dynamic DOM privacy helpers, and parent-delegated session controls.

Ordinary consumers do not implement Cobrowse startup or shutdown. An approved dedicated Cobrowse application may call invsy.cobrowse.startSession(), endSession(), getSessionState(), and onSessionStateChange(); these methods delegate to the parent and never receive the licence. Static reviewed DOM can use data-cobrowse-visible; dynamic content can use the narrow Invsy privacy helpers where declarative markup is not possible.

Related pages

• Plugin overview
• Extension patterns
• Livechat