Configuration Options
UserView's installation code includes the Upscope('init', {}); function, which accepts a dictionary of options as its second parameter. Most of these options can be configured through the UserView dashboard.
Some settings might not be available with your plan or may only be accessible if you have beta features enabled.
Please use the dashboard
Setting these values through JavaScript is only recommended if you can't configure them through the dashboard and have a specific use case where each page needs to behave differently. Values set through JavaScript will override your dashboard settings. You can configure most of these settings in the dashboard.
Identifying the Visitor
You can use these settings to identify the visitor within UserView.
| 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 cannot contain spaces. If set to null, the identity info is cleared. If not set, nothing is changed. |
uniqueId | undefined | A string to uniquely identify the visitor (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. |
integrationIds | undefined | A list of IDs that can be used to link the visitor to different records. Example: ["system_name:system_value"]. New integration IDs are added to existing ones unless cleared like this: ["system_name:"]. |
metadata | undefined | A Record object with metadata related to the visitor. |
secretKey | undefined | An optional string required in all pageviews to match. If it doesn't match, a new visitor will be generated. There is no way to retrieve the secretKey, so no other actors would have access to it. |
Agent Prompt
Use these settings to show extra information about the visitor to the agent. This can also be used to provide the agent with instructions on troubleshooting 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 the URL for the visitor. |
allowFullScreen | (Set through the admin interface) | Whether to allow full screen mode during sessions. |
allowRequestFullTab | (Set through the admin interface) | Whether to allow agents to request full tab sharing. |
allowRemoteClick | (Set through the admin interface) | Whether to allow agents to click for the visitor. |
agentRequestButtonPages | (Set through the admin interface) | Pages on which to show the agent request button (e.g. ['https://site.com/help/*']). |
agentRequestButtonStyle | (Set through the admin interface) | Position and style of the agent request button. |
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 use the visitor's keyboard. |
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 the server automatically. |
automaticallyRequestFullTab | (Set through the admin interface) | Whether to automatically request full tab sharing when a session starts. |
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. |
disableFullScreenWhenMasked | false | Whether to disable full screen mode when masked elements are present on the page. |
disconnectAfterSeconds | 900 | Number of seconds of inactivity after which the SDK 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. |
enableSessionRating | (Set through the admin interface) | Whether to show a session rating prompt to the visitor after a session ends. |
endOfScreenshareMessage | (Set through the admin interface) | Message shown at the end of the session. |
enlargeCursor | false | Whether to enlarge the visitor's cursor so it looks like the agent's. |
compressImages | true | Whether to compress and canvas content that is sent from the visitor's browser. Set to false if you have high definition canvases. |
grabIdentityFromLivechat | true | Whether to 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 region to connect to. |
requireAuthorizationForSession | (Set through the admin interface) | Whether to ask for visitor authorization before screen sharing. |
requireControlRequest | (Set through the admin interface) | Whether to ask the visitor separately for remote control capabilities. |
rewriteExternalLinks | (Set through the admin interface) | Whether to 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. |
showAgentRequestButton | (Set through the admin interface) | Whether to show the visitor the request agent button (one of "always", "when_available", or "never"). |
storageImplementation | localStorage + cookies | An object that implements the Storage interface to use as storage for all visitor data. |
storageKey | null | An optional string to use to scope all visitor data stored on the browser. |
screenWakeLock | true | Whether to attempt to place a screen lock during sessions. |
trackConsole | (Set through the admin interface) | Whether to track console content to display to the viewer. |
unavailableAgentRequestRedirectTo | null | URL to redirect the visitor to when no agents are available after requesting an agent. |
unavailableAgentRequestRedirectImmediately | false | Whether to redirect immediately when no agents are available, instead of showing the unavailable message first. |
useFingerprinting | true | Whether to use a device fingerprint to recognize the device cross-domain. |
computedStyleSelectors | [] | A list of selectors that need to have the entire computed style sent from the browser (as the CSS won't be available to the agent). You can set to "react" if your whole app is built in React or "angular" if it's built in Angular, and we'll automatically send everything not added by React or Angular, such as elements injected by browser extensions. |
Messages
These settings are mostly translations.
| Option | Default Value | Description |
|---|---|---|
agentRequestAcceptedText | (Set through the admin interface) | Text shown when an agent request is accepted. |
agentRequestButtonRequestingSubtitle | (Set through the admin interface) | Subtitle shown on the agent request button while requesting. |
agentRequestButtonRequestingTitle | (Set through the admin interface) | Title shown on the agent request button while requesting. |
agentRequestButtonSubtitle | (Set through the admin interface) | Subtitle shown on the agent request button. |
agentRequestButtonTitle | (Set through the admin interface) | Title shown on the agent request button. |
agentRequestNotAvailableText | (Set through the admin interface) | Text shown when no agents are available. |
agentRequestResultTitle | (Set through the admin interface) | Title shown in the agent request result popup. |
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 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. |
callAudioAuthorizationFailedMessage | (Set through the admin interface) | Message shown when audio authorization fails during a call. |
callAudioAuthorizationFailedTitle | (Set through the admin interface) | Title shown when audio authorization fails during a call. |
callPopupFailedMessage | (Set through the admin interface) | Message shown when the call popup fails. |
callPopupFailedTitle | (Set through the admin interface) | Title shown when the call popup fails. |
callPopupNoInputMessage | (Set through the admin interface) | Message shown when no audio input device is found. |
callPopupNoInputTitle | (Set through the admin interface) | Title shown when no audio input device is found. |
callPopupNoOutputMessage | (Set through the admin interface) | Message shown when no audio output device is found. |
callPopupNoOutputTitle | (Set through the admin interface) | Title shown when no audio output device is found. |
callPromptText | (Set through the admin interface) | Message to show the visitor when an audio call is initiated. |
controlRequestTitle | (Set through the admin interface) | The title to display on the control prompt. |
controlRequestMessage | (Set through the admin interface) | Message to display on the control prompt. |
fullScreenRequestTitle | (Set through the admin interface) | The title to display on the full screen prompt. |
fullScreenRequestMessage | (Set through the admin interface) | Message to display on the full screen prompt. |
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. |
sessionRatingAgentLabel | (Set through the admin interface) | Label for the agent rating field in the session rating prompt. |
sessionRatingFeedbackLabel | (Set through the admin interface) | Label for the feedback field in the session rating prompt. |
sessionRatingModalMessage | (Set through the admin interface) | Message shown in the session rating modal. |
sessionRatingModalTitle | (Set through the admin interface) | Title of the session rating modal. |
sessionRatingSessionLabel | (Set through the admin interface) | Label for the session rating field in the session rating prompt. |
sessionRatingSubmitLabel | (Set through the admin interface) | Label for the submit button in the session rating prompt. |
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 UserView 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. |
customControlRequestController | (cb: function) | Boolean (via callback) | Set to a function to change the look of the control request view. Return true to accept the control request, false to reject it. |
customFullScreenRequestController | (cb: function) | Boolean (via callback) | Set to a function to change the look of the full screen request view. Return true to accept the full screen request, 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. |
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. |
shouldComputeStyleMiddleware | (element: HTMLElement) | Boolean | Set to change the behavior of whether we get the computed style of a particular element before sending it to the agent. |
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 its source from the server. Useful for libraries such as styled-components. |