Cobrowse Visitor API

The Visitor API allows you to customize the visitor side behavior of Cobrowse.

GLANCE_COBROWSE

You can control Cobrowse parameters by setting properties on the JavaScript object window.GLANCE_COBROWSE.

Properties

The following properties can be set on GLANCE_COBROWSE. These properties, apart from getMaskingDescriptor, would typically be set if the visitor is logged in and the information is known at the time the page is rendered. Any or all these properties may be set.

If name, email, and phone number are defined prior to the cobrowse script initializing, those values are stored with that session participant's record in the Glance database once the session starts.

Example

GLANCE_COBROWSE = {
  visitorid: "59204gh-42",
  name: "Joe Smith",
  email: "jsmith@example.com",
  phone: "314-555-1212"
};

GLANCE.Cobrowse.Visitor

The GLANCE.Cobrowse.Visitor object is defined in any web page that includes the Glance Cobrowse script tag. Sample code which implements a Cobrowse user interface using GLANCE.Cobrowse.Visitor can be found here.

Properties and Methods

The following properties and methods are available on GLANCE.Cobrowse.Visitor. (Methods marked with an asterisk * can only be called when there is an active session).

Using GLANCE.Cobrowse.Visitor methods

Using startSession()

startSession() starts a Cobrowse session. You may use it in one of two ways:

1. startSession(key) uses a specific string key for the new session. Keys can be up to 100 characters (letters, numbers, _, -, ~). If you pass "GLANCE_KEYTYPE_RANDOM", a random key is generated.
2. startSession(options) starts a session using a configuration object.

The options object may contain:

• groupid: (Optional) ID of the Glance group. Defaults to the data-groupid in the script tag.
• sessionKey: (Optional) The session key.
• name, email, phone: Visitor details.

If starting with video (and the agent has multiparticipant privileges), you can include:

• video: "large", "small", "off"
• videosource: Device ID of the camera
• previewelementid: ID of video preview element (defaults to glance_videopreview)
• camerastatus: "blocked", "nocamera", "available", "error"
• videopaused: true to start paused, false to start active.

Examples

// Start with a specific key
GLANCE.Cobrowse.Visitor.startSession("ABCD");

// Start with a random key
GLANCE.Cobrowse.Visitor.startSession("GLANCE_KEYTYPE_RANDOM");

// Start in large video mode
GLANCE.Cobrowse.Visitor.startSession({ video: 'large' });

// Start with multiple parameters
var options = {
  sessionKey: "ABCD",
  name: "Julie Smith",
  email: "jsmith@example.com",
  phone: "314-555-1212"
};
GLANCE.Cobrowse.Visitor.startSession(options);

Using crossDomain()

See Cobrowse Cross-Domain for complete details.

crossDomain(options) sends session information to domains in your Cross Domain trust list. It returns a Promise. Because it opens a temporary pop-up window, it must be called in response to a user action (click/keystroke) to avoid pop-up blockers.

Alternatively, promptCrossDomain(options) (see VisitorUI API) prompts the user first, avoiding blocker issues entirely.

Options:

• url: The URL to open.
• target: "_self" or "_blank".

Using pauseSession

pauseSession(params) freezes the view on the agent's side. If you want the session to start paused on load, add data-startpaused="1" to the cobrowse script tag. This prevents a race condition where the page uploads before the pause function is called.

While paused, no page updates are sent. If a message is specified, it overlays the frozen view. Navigating to a new page unpauses the session unless the new page also has data-startpaused="1". Single Page Applications (SPAs) like React can call this dynamically during view changes.

// Pause and show message
GLANCE.Cobrowse.Visitor.pauseSession({ pause: true, message: "This session is paused." });

// Unpause
GLANCE.Cobrowse.Visitor.pauseSession({ pause: false });

Using notifyChanged()

Browsers cannot automatically notify the script when <canvas> elements change. You must manually call notifyChanged() so graphs or drawings render correctly for the agent. The script identifies canvases using the data-gcid attribute.

Example

if (GLANCE && GLANCE.Cobrowse && GLANCE.Cobrowse.Visitor) {
  var canvases = { 
    canvas: { 
      gcids: [$("#c1").attr("data-gcid"), $("#c2").attr("data-gcid")] 
    }
  };
  GLANCE.Cobrowse.Visitor.notifyChanged(canvases);
}

Using getMaskingDescriptor()

Glance provides a hook function to dynamically customize page and element masking: window.GLANCE_COBROWSE.getMaskingDescriptor(params).

This hook must be included in the page before the Glance script loads. The script calls this hook on every page navigation before sending contents to the agent. It should return a Promise resolving to a masking descriptor:

{
  "maskpage": false, 
  "maskedelements": [".sensitive-data", "#ssn-field"]
}

The script also calls this hook (passing an agents object) whenever an agent or guest joins/leaves. If the hook returns new rules, a full update is sent to the agent.

Note: The "maskpage" property overrides the group-level Allow/Deny list, and "maskedelements" are applied in addition to any selectors configured in your Glance group settings.

If the Promise rejects, the entire page is masked for security.

Parameters passed to getMaskingDescriptor

If known, agent information is passed via { agents: [agent information] }:

{
  "count": 2,
  "agentlist": [
    {
      "username": "fred.glance.net",
      "guestid": 42309845,
      "partnerid": 12345,
      "partneruserid": "fred@myco.com",
      "name": "Fred O'Hare",
      "role": "agent",
      "agentrole": "Business Unit 1",
      "num": 1
    }
  ]
}

Masking Based on Web Service Example

GLANCE_COBROWSE.getMaskingDescriptor = async function () {
  return new Promise(async (resolve, reject) => {
    let agenttoken = Cookies.get("agenttoken");
    let maskinginfo = await fetch(`/api/GetAgentMaskRules?id=${agenttoken}`);
    
    if (!maskinginfo.ok) {
      reject("Error attempting to query masking info");
    } else {
      let data = await maskinginfo.json();
      resolve({
        "maskpage": false,
        "maskedelements": data.maskedelements
      });
    }
  });
}

Role-Based Masking Example

Masking elements dynamically based on the specific agentrole of the agent in the session.

GLANCE_COBROWSE.getMaskingDescriptor = async function (params) {
  return new Promise(async (resolve, reject) => {
    let maskingdescriptor = {};

    // If agent info isn't available yet, mask all role-specific fields
    if (!params.agents || params.agents.count === 0) {
      maskingdescriptor.maskedelements = ["[data-agentrole]"];
    } else {
      // Mask fields that do NOT match the current agent's role
      let currentRole = params.agents.agentlist[0].agentrole.toLowerCase();
      maskingdescriptor.maskedelements = [`[data-agentrole]:not([data-agentrole='${currentRole}'])`];
    }

    resolve(maskingdescriptor);
  });
}