Co-browse API

This API provides methods and callbacks to work with Co-browse and can be used to implement a custom UI for co-browsing.

Important

See Integrated JavaScript Application#Obtaining Chat and Co-browse APIs for information on accessing this API.

Co-browse in iframes

Some Co-browse UI elements such as the the co-browsing button and toolbar should not appear when Co-browse is in an iframe. Common Co-browse UI elements such as notifications that an element is masked should appear whether or no Co-browse is in an iframe. As such, there are two contexts for the Co-browse JavaScript API:

• Top context, available when Co-browse is not rendered in an iframe.
• Child context, used when a page is rendered in an iframe. For the child context, a subset of the top context API is available.

isTopContext

The isTopContext variable can be used determine which context Co-browse is rendered in. isTopContext is passed to the onReady method and equals true if Co-browse is rendered in the top context and false otherwise.

Example:

var _genesys = {
    cobrowse: {
        onReady: function(api, isTopContext) {
            // common functionality
            api.onMaskedElement.add(function() {/* deal with masked elements here*/});
            if (!isTopContext) {
                return;
            }
            // top context functionality goes below
    }
};

Tip

See Documentation:GWE:Developer:GCBIntegration#Obtaining_Chat_and_Co-browse_APIs Integrated JavaScript Application#Obtaining Chat and Co-browse APIs if you are unfamiliar with the onReady syntax above.

Signals and Callbacks

The Co-browse API exposes a number of signals in both the top and child contexts. Each signal is object with the three following methods:

• add(function)—adds a callback
• addOnce(function)—adds a callback that will be executed only once
• remove(function)—removes a callback

The naming convention for signal names begins with "on" and follows the format onSomethingHappened.

Important

Signals act similar to deferred objects. If you add a callback to an event that has already happened, the callback will be called immediately. For example, if you add a callback to the onAgentJoined signal when the event has already happened, the callback will be called immediately.

Session Object

Many callbacks receive a session object as an argument. This object has the following properties:

• token—String containing the session token shared with the agent and possibly shown in the UI. The token is a 9 digit string such as "535176834".
• agents—Array of connected agents. Each element in the array is an object with no properties.

Common API

The following elements and properties are available from both the top and child Co-browse contexts:

markServiceElement(element)

Service elements do not show up in the agent's view. This function is used to mark service elements in a custom Co-browse UI.

Arguments:

• element—HTML element that will be masked.

Important

Elements must be marked as service elements before they are added to the DOM

Important

The markServiceElement() method should not be used to hide sensitive information. Business functions like DOM Control or Data Masking should be used for sensitive content such as private user data.

Plain DOM Example:

function createCustomCobrowseUI(cobrowseApi) {
    var toolbar = document.createElement('div');
    toolbar.className = 'cobrowseToolbar';
    toolbar.textContent = 'Co-browse is going on';
    cobrowseApi.markServiceElement(toolbar); // don't show the toolbar to agents
    cobrowseApi.onConnected.add(function() {
        document.body.appendChild(toolbar);
    })
}

jQuery Example:

// Create a simple jQuery plugin
$.fn.cbMarkNode = function() {
    return this.each(function() {
        cobrowseApi.markServiceElement(this);
    });
};
 
// And then:
$('<div class="cobrowseToolbar">Co-browse is going on</div>').cbMarkNode().appendTo('body');

onMaskedElement

This signal is dispatched when Co-browse encounters an element that is subject to data masking.

Arguments:

• element—HTML Element

This signal is dispatched multiple times when Co-browse initiates and can be dispatched again if a masked element is added to the page dynamically.

Example:

cobrowseApi.onMaskedElement.add(function(element) {
    $(element).tooltip({
        content: 'Content of this elements is masked for representatives.'
    });
});

Top Context API

The following methods and properties are available only when Co-browse is rendered in the top context.

isBrowserSupported()

This method returns a boolean with the value of true when the browser is supported and false otherwise. The built-in integration module uses this function to show a message if a user tries to start Co-browse in an unsupported browser. You may use it, for example, to hide the Co-browse button completely.

startSession()

This method instantiates a new Co-browse session. It will throw an error if the browser is not supported.

exitSession()

This method exits and ends an ongoing Co-browse session.

onInitialized

This signal is dispatched after the page is loaded and the Co-browse business logic is initialized.

Arguments:

• session— Session object representing the ongoing session or null if there is no ongoing session.

Example:

cobrowseApi.onInitialized.add(function(session) {
    if (!session) {
        showCobrowseButton();
    } else {
        showCobrowseToolbar(session);
    }
})

onSessionStarted

This signal is dispatched when a Co-browse session is successfully started and joined by the master such as when the Co-browse button is pressed or when startSession() is called.

Arguments:

• session—Session object representing the ongoing session.

Example:

function notifyCobrowseStarted(session) {
    alert('Co-browse has started. Spell this session token to our representative: ' + session.token);
}
cobrowseApi.onSessionStarted.add(notifyCobrowseStarted);

onAgentJoined

This signal is dispatched when an agent successfully joins a session.

Arguments:

• agent—Object representing the new agent. This object has no properties.
• session—Session object representing the ongoing session.

Example:

cobrowseApi.onAgentJoined.add(function(agent, session) {
    alert('Representative has joined the session');
});

onAgentNavigated

This signal is dispatched when the slave user initiates navigation such as refresh, back, forward, or when the agent enters a URL into the slave Co-browse UI. Signal is dispatched a few seconds before the navigation happens. This can be used to, for example, send a warning to the user or disable the Exit session button before navigation.

Arguments:

• details—Object containing the following navigation detail fields:
  • command—String with the value of back, refresh, forward, or url.
  • url—Optional string that is present only if the command field has the value of url

Example:

// Let's assume we have a "growl" function available to show growl-like notifications
cobrowseApi.onAgentNavigated.add(function(details) {
    if (details.url) {
        growl('Representative navigated to the page: ' + details.url);
    } else {
        growl('Representative has pressed the "' + details.command + '" button. Page will be refreshed');
    }
});

onNavigationFailed

This signal is dispatched when the navigation request from the agent fails to execute such as when the agent navigates forward when there is no forward history. You can use this signal to to re-enable the Exit button and/or show a notification.

The callback receives no arguments.

Example:

// Let's assume we have a "growl" function available to show growl-like notifications
cobrowseApi.onNavigationFailed.add(function() {
    growl('Navigation request by representative has failed');
});

onSessionEnded

This signal is dispatched when a Co-browse session ends.

Arguments:

• details—Object with the follwing field:
  • reason—Field with value of a string or undefined. Possible string values:
    • self—The user has exited the session by clicking the Exit button or calling the exitSession() API method.
    • external—The agent has closed the session. Some server errors may also result in this value.
    • timeout—The session has timed out such as when a user reopens a page with an expired Co-browse cookie.
    • intactivityTimeout—The agent did not join a session in the configured amount of time.
    • error—There is an error such as a critical misconfiguration.

Example:

var cbEndedMessages = {
    self: 'You exited Co-browse session. Co-browse terminated',
    external: 'Co-browse session ended',
    timeout: 'Co-browse session timed out',
    inactivityTimeout: 'Agent did not join. Closing Co-browse session.',
}
cobrowseApi.onSessionEnded.add(function(details) {
    alert(cbEndedMessages[details.reason] || 'Something went wrong. Co-browse terminated.');
    showCobrowseButton();
});