Documentation

    Installation

    Overview

    Co-Browsing API can be installed using one of the following methods:

    1. Installing via Script Tag - Directly add the code snippet to your web page.
    2. Installing via NPM - Ideal for projects using a Node.js environment.
    3. Installing via React - For React-based applications.

    Choose the method that best fits your project's requirements.

    You'll find your installation code within your Co-Browsing API dashboard. Simply add the code anywhere on your webpage, or, if you prefer, add it to a JavaScript file by removing the tags from the code.

    Recommendation: Make sure that the code loads as fast as possible by adding it as one of the first things that execute on the page.

    Warning
    While you can install Co-Browsing API through Google Tag Manager or Segment, the preferred method is to paste the installation code directly on your website, as this will result in faster load times.

    Installation remains the same whatever front end framework you use. Co-Browsing API works fine with React, Angular, and most other modern JavaScript frameworks. All you need to do is add the code to the page.

    Testing on a Local or Staging Environment

    When you test on your own computer or in a staging environment that is not publicly accessible, you might notice some odd rendering issues.

    This is because our proxy server is unable to reach your CSS and media files and therefore can't properly edit them to render on the Agent side.

    We try to automatically detect if you are on a URL that looks like localhost (e.g. http://127.0.0.1/, http://localhost/, etc.), and send the content of CSS files directly from the Visitor's browser to the Agent's browser.

    You can add more URLs for browser proxying in your dashboard settings.

    Iframe Support

    Co-Browsing API will work with iframes without you needing to do anything when these are hosted on the same domain. This means that the part of the URL between :// and the first / is exactly the same (i.e. app.acme.com and dashboard.acme.com are considered different domains).

    In this case, you only need to add the script to the outermost frame (i.e. the parent page).

    You don't need to do anything to make Co-Browsing API work cross-domain if iframes aren't involved.

    Different Domains

    To make Co-Browsing API work when you have iframes on different domains/subdomains, you'll need to add the code to all the iframes. This is the code you get from your dashboard's installation page.

    The iframes will connect automatically.

    Using the SDK
    The code will behave differently in the iframe, and you can't use SDK within it. That means that if you want to identify the user you'll need to do so in the outermost frame.

    Sharing Only Part of the Page

    By default, Co-Browsing API shares the entire page. If you only want to share a specific part of your content (for example, a document viewer or a preview area), place that content in a same-origin iframe and pass the iframe's contentWindow as the sharingRoot configuration option. Only the iframe's document will be shared — everything outside it stays private.

    <iframe id="shared-content" src="/shared-content"></iframe>

    const iframe = document.querySelector('#shared-content');
iframe.addEventListener('load', () => {
  Upscope('init', {
    sharingRoot: iframe.contentWindow
  });
});

    Make sure the iframe has finished loading before initializing, as shown above, so that contentWindow points to the final document.

    If you're using React, pass sharingRoot as a prop to the UpscopeProvider, enabling it once the iframe is available:

    function SharedContent() {
  const [contentWindow, setContentWindow] = useState(null);
  return (
    <UpscopeProvider
      apiKey="<public_api_key>"
      enabled={!!contentWindow}
      sharingRoot={contentWindow}
    >
      <iframe
        src="/shared-content"
        onLoad={(e) => setContentWindow(e.target.contentWindow)}
      />
    </UpscopeProvider>
  );
}
    Same origin required
    The sharingRoot window must be on the same origin as the page running the SDK. Cross-origin iframes cannot be used as the sharing root; for those, follow the Different Domains instructions instead.

    When You Have a Lot of Visitors

    If your website has a lot of Visitors (i.e. over 5,000 connected at once), you might want to only connect Visitors who actually need help.

    You can easily do this by passing autoconnect: false to the configuration, like this (or by turning this off in the dashboard):

    // Rest of the installation code...
Upscope('init', {
 autoconnect: false
})

    The visitor will be connected automatically if they have recently been in a Session, and will also automatically connect if they are shown the lookup code through any means.

    You can also manually connect the Visitor by calling Upscope('connect');

    CSP Rules

    If you use Content Security Policy rules to protect your website, you'll need to add the following URLs to allow Co-Browsing API to work correctly.

    script-src 'self' https://code.upscope.io https://js.upscope.io;
connect-src wss://*.upscope.io https://*.upscope.io;
media-src https://js.upscope.io;
img-src https://app.upscope.io https://app-cdn.upscope.io;

    Prototype.js

    To make Co-Browsing API compatible with some older versions of Prototype, include the following code before the installation code.

    <script>
  if (window.Prototype) {
    delete Object.prototype.toJSON;
    delete Array.prototype.toJSON;
    delete Hash.prototype.toJSON;
    delete String.prototype.toJSON;
  }
</script>