Installation

You'll find your Upscope installation code here.

You can add the code anywhere on the page, and if you prefer you can add it to a javascript file by removing the <script> and </script> tags from the code.

We recommend making sure that the code loads as fast as possible by making it one of the first things that execute on the page.

Warning

While you can install Upscope 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. Upscope 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 Upscope 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 (such as your staging environment) here.

Iframe support

Upscope 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 Upscope script to the outermost frame (i.e. the parent page).

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

Different domains

To make Upscope work when you have iframes on different domains / subdomains, you'll need to add the Upscope code to all the iframes. This is the code you get from https://app.upscope.io/install.

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.

Client-side Form Validation

JavaScript validation will work on the user side but will not work on the agent side. To ensure validations work on both agent AND user side we recommend using HTML validation. Learn more about HTML validation here.

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 Upscope 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;

WebGL Support

The way WebGL is implemented in most browsers prevents Upscope from grabbing the content of the canvas. You can make a few changes to your code to allow Upscope to work with WebGL.

Somewhere in your code, you'll be grabbing the webGL context by doing:

canvas.getContext('webgl')

This needs to be changed into this:

canvas.getContext('webgl', { preserveDrawingBuffer: true })

If you don't want to edit your code, or don't know how to; or simply want to test that this approach works before making changes, you can add the following code before any other javascript code to automatically apply the above change everywhere:

<script>
  HTMLCanvasElement.prototype.__getContext = HTMLCanvasElement.prototype.getContext;
  HTMLCanvasElement.prototype.getContext = function(t, ...args) {
    if(t === 'webgl') return this.__getContext('webgl', { ...args, preserveDrawingBuffer: true });
    if(t === 'webgl2') return this.__getContext('webgl2', { ...args, preserveDrawingBuffer: true });
    return this.__getContext(t, ...args);
  }
</script>

Prototype.js

To make Upscope compatible with some older versions of Prototype, include the following code before the Upscope installation code.

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