JavaScript SDK

Configuration Options

Configuration options

Upscope's installation code has a Upscope('init', {}); function that takes as second parameter a dictionary of options. Most of these can be set through the Upscope dashboard.

Some of these settings might not be available with your plan or might only be available if you have beta features enabled.

Please use the dashboard

Setting these values through the javascript is only encouraged if you can't set them through the dashboard as you have a specific use case where each page needs to behave differently.
Values set through the javascript will override your dashboard settings.
You can set most of these settings here.

Identifying the visitor

You can use these settings to identify the visitor within Upscope.

Option	Default value	Description
`identities`	`undefined`	A list of strings to identify the visitor by (e.g. `['Joe Smith', 'joe@smith.com']`). If set to `null`, the identity info is cleared. If not set, nothing is changed. With some integrations this is set automatically if left empty.
`tags`	`undefined`	A list of strings to tag the visitor with (e.g. `['#visitor', '#high-value']`). Tags can only be alphanumeric characters, and can contain no spaces. If set to `null`, the identity info is cleared. If not set, nothing is changed.
`uniqueId`	`undefined`	A strings you uniquely identify the visitor by (e.g. `123`). If set to `null`, the id is cleared. If not set, nothing is changed. With some integrations this is set automatically if left empty.

Agent prompt

You can use show extra information about the Visitor to the Agent. This can also be used to show the Agent instructions on how to troubleshoot common problems with the specific page.

Option	Default value	Description
`agentPrompt`	`undefined`	A string of text containing information to be presented to the Agent about the Visitor.

Additional configuration

These settings control how the session behaves on this particular page.

Option	Default value	Description
`allowAgentRedirect`	(Set through the admin interface)	Whether to allow agents to change URL for the visitor.
`allowRemoteClick`	(Set through the admin interface)	Whether to allow agents to click for the visitor.
`allowRemoteConsole`	(Set through the admin interface)	Whether to allow agents (who have the right permissions) to execute remote console commands
`allowRemoteScroll`	(Set through the admin interface)	Whether to allow agents to scroll for the visitor.
`allowRemoteType`	(Set through the admin interface)	Whether to allow agents to scroll for the visitor.
`apiKey`	(Automatically set to your API key)	The API key of the account to connect to
`autoconnect`	(Set through the admin interface)	Whether to connect to Upscope server automatically.
`callRingtone`	(Default ringtone)	An mp3 of the ringtone for audio calls.
`collectHistory`	(Set through the admin interface)	Whether to take screenshots and record pageviews to show in integrations.
`cursorColor`	`null`	The color to use for the enlarged cursor.
`disconnectAfterSeconds`	`900`	Number of seconds of inactivity after which Upscope disconnects from the server. This only applies if a session is not active, and the connection is re-established when the tab regains focus, the cursor is moved, or the keyboard is used.
`domChangesDelay`	`100`	Refresh rate of the page. Set to 100 so changes are shown right away, but can be higher on websites where a lot changes constantly to avoid the agent's browser slowing down.
`drawingsTtlMs`	`6000`	How long to keep agent drawings visible for.
`enableCanvases`	`true`	Whether to show canvases while screen sharing.
`enableLookupCodeOnKey`	(Set through the admin interface)	Whether to show the lookup code when the visitor presses the lookupCodeKey lookupCodeKeyRepetitions times.
`endOfScreenshareMessage`	(Set through the admin interface)	Message shown at the end of the session.
`enlargeCursor`	`false`	Whether to enlarge the Visitor's so it looks like the Agent's.
`grabIdentityFromLivechat`	`true`	Whether try to get the identity of the visitor from the live chat configuration.
`injectLookupCodeButton`	(Set through the admin interface)	Whether to inject a button in the lower left of the page to show the 4 digit lookup code.
`integrateWithLivechat`	`true`	Whether to integrate automatically with live chat systems.
`liveChatRewrite`	`true`	Whether to change the live chat integration object to automatically include the watch link as a custom attribute.
`lookupCodeButtonPages`	(Set through the admin interface)	Pages on which to show the lookup code button (e.g. ['https://site.com/help/*'])
`lookupCodeButtonStyle`	(Set through the admin interface)	Position of the lookup code button.
`lookupCodeElement`	(Set through the admin interface)	CSS selector or HTML element object to replace text of with 4 digit lookup code.
`lookupCodeKey`	`17`	Which keyboard key to show the lookup code with (17 is the Ctrl key).
`lookupCodeKeyRepetitions`	`5`	Number of times the visitor needs to press lookupCodeKey to see the lookup code.
`maskedElements`	(Set through the admin interface)	List of CSS selectors (e.g. ['.credit-card']) to mask when screen sharing in addition to elements with a no-upscope CSS class.
`noRemoteElements`	(Set through the admin interface)	List of CSS selectors for elements where the agent should not have the ability to click / type.
`proxyAssets`	(Set through the admin interface)	List of wildcard strings (e.g. `['://localhost:/*']`) to proxy from the browser when screen sharing. This is useful to allow screen sharing in development or staging environments.
`region`	(Visitor's closest region)	Which Upscope region to connect to.
`requireAuthorizationForSession`	(Set through the admin interface)	Whether to ask for visitor authorization before screen sharing.
`rewriteExternalLinks`	(Set through the admin interface)	Whether automatically change links to third party websites to make use of our proxy.
`sfdcFieldId`	`"Screen_Share__c"`	For Salesforce integration, the ID of the field we send the watch link to.
`sfdcFieldLabel`	`"Screen_Share"`	For Salesforce integration, the label of the field we send the watch link to.
`showTerminateButton`	(Set through the admin interface)	Whether to show the visitor a "Stop session" button.
`storageImplementation`	`localStorage` + cookies	An object that implements the Storage interface to use as storage for all Visitor data.
`trackConsole`	(Set through the admin interface)	Whether to track console content to display to the viewer.
`useFingerprinting`	`true`	Whether to use a device fingerprint to recognize the device cross-domain.

Messages

These settings are mostly translations.

Option	Default value	Description
`authorizationPromptMessage`	(Set through the admin interface)	The text to display on the authorization prompt. `{%agentName%\|our agent}` is replaced with the name of the requesting agent (or the default `our agent` (or the default our agent if there is no name). `{%currentDomain%}` is replaced with the current hostname.
`authorizationPromptTitle`	(Set through the admin interface)	The title to display on the authorization prompt.
`callPromptText`	(Set through the admin interface)	Message to show visitor when an audio call is initiated.
`callWaitMessage`	(Set through the admin interface)	This text will be shown to the visitor when they follow a call link.
`lookupCodeKeyMessage`	(Set through the admin interface)	Message of prompt with the lookup code. `{%lookupCode%}` is replaced with the lookup code.
`lookupCodeKeyTitle`	(Set through the admin interface)	Title of prompt with the lookup code.
`translationsNo`	(Set through the admin interface)	Translation for No.
`translationsOk`	(Set through the admin interface)	Translation for Ok.
`translationsStopSession`	(Set through the admin interface)	Translation for End Session.
`translationsYes`	(Set through the admin interface)	Translation for Yes.

Functions

You can pass the following functions to further customize how Upscope behaves.

Option	Arguments	Return value	Description
`allowRemoteMiddleware`	`(element: HTMLElement)`	Boolean	Set to change the behavior of the remote control functionality. Return `true` if the agent should have control over the element, `false` if they should not have control.
`customCallController`	`(cb: function)`	Boolean (via callback)	Set to a function to change the look of the audio call ringing view. Return `true` to accept the call, `false` to reject it.
`maskElementMiddleware`	`(element: HTMLElement)`	Boolean	Set to change the behavior of the masking functionality. Return `true` if the element should be masked, `false` if it should not be masked.
`needsProxy`	`(url: string)`	Boolean	Set to a function to change the behavior of whether a particular URL leads to the Upscope proxy or not. Return `true` if the proxy is needed, `false` if the URL will have the Upscope SDK installed on it or you do not wish the session to continue.
`onSessionRequest`	`(cb: function, requestingAgent: string?)`	Boolean (via callback)	Set to change the behavior of the visitor authorization flow. Call the callback with `true` to authorize the session, with `false` to reject it.
`styleSheetContentFromRules`	`(element: HTMLElement)`	Boolean	Set to change the behavior of whether we get the content of a stylesheet from its rules, or whether we can proxy it's source from the server. Useful for libraries such as `styled-components`