Co-Browsing session options
Here, you can find the reference tables for each of the Surfly session options. You can choose the aspects of Surfly's functionality you want to integrate into your website and personalize your co-browsing sessions. These parameters can be set in the options panel or used in the Javascript or REST API.
Changes to the code will take priority over changes to the options panel
Group Reference Tables
Chat box
| Option | Default | Description |
|---|---|---|
| chat_enabled | true | Enable text chat. |
Pause functionality
| Option | Default | Description |
|---|---|---|
| pause_enabled | false | Enable session pause. Participants can pause their tabs from syncronization. Others will see the page paused and greyed out. |
Screenshots
Options below set the default screenshots settings.
| Option | Default | Description |
|---|---|---|
| s3_screenshots_bucket | "" | AWS S3 bucket name for screenshots |
| automatic_screenshots_enabled | false | Enable automatic screenshots. To use this functionality, please configure s3_screenshots_bucket, s3_access_key, and s3_access_secret appropriately |
| screenshot_image_size | 1920 | Width of the the screenshot. s3_screenshots_bucket is required to enable screenshots functionality. |
| screenshot_interval | 15 | Wait this many seconds between automatic screenshots. (Note: values lower than 15 may diminish the quality of the session.) |
| screenshots_on_annotation | false | Take a screenshot after each annotation or drawing. To use this functionality, please set drawing_enabled to true and configure s3_screenshots_bucket, s3_access_key, and s3_access_secret appropriately. |
| use_webrtc_for_screenshots | false | Uses WebRTC to make screenshots. Source of the screenshots is a session tab of the first Agent that joins. Agents are required to use Google Chrome. |
Video
| Option | Default | Description |
|---|---|---|
| videochat | true | Is videochat allowed? Note that videochat functionality is disabled in browsers that don't support WebRTC, such as Internet Explorer and Chrome on iOS |
| start_with_videochat_on | false | Start the session with videochat on. |
| start_with_fullscreen_videochat | false | Start videochat in fullscreen mode. |
| videochat_prompt | true | When this option is set to false and videochat is started inside a session, other participants will not be prompted to join the videochat. Instead, they will join automatically with disabled mic and camera. |
| video_archiving_enabled | false | Enable Vonage videochat recording. |
| p2p_videochat_enabled | true | Use peer-to-peer connections for videochat. If set to true, video_archiving_enabled will be disabled. |
| screensharing_enabled | true | Allow users to share desktop applications. Please enable videochat_enabled to use this feature. |
| anonymous_users_can_share_camera | true | When set to false, only authenticated users will have the capability to share their camera feed within video chats. Meanwhile, other users can still participate in the videochat but will be restricted to audio-only sharing. |
| default_videochat_fullscreen_mode | 'grid' | Default videochat fullscreen mode. Can be either 'grid' or 'spotlight'. |
| default_videochat_mode | 'floating' | Default videochat mode. Can be either 'floating' or 'sidebar'. |
The Peer-to-peer (p2p) option connects all participants directly with one another. Thus, videochat recordings feature is not available when this option is enabled. With more than 5 videochat participants it is possible that video quality will decrease.
When this option is off, the Routing mode is used. It connects all participants by routing each participant through the server, which enables videochat recordings, and diminishes quality loss with large amount of videochat participants.
File sharing
| Option | Default | Description |
|---|---|---|
| filesharing_enabled | true | Enable file sharing. |
| original_file_download_allowed | false | Allow users to download shared files. If set to false, users can still view shared files but will not be able to download them. |
| document_editor_enabled | true | Enable editing in the document viewer interface. |
| document_viewer | multi-format | Select "pdf" for PDF file support or "multi-format" for extended document format compatibility. |
Session recording
| Option | Default | Description |
|---|---|---|
| automated_session_recording_enabled | false | Enable session recording. Recordings will be stored in the S3-compatible bucket specified with s3_recordings_bucket using the credentials provided in s3_access_key and s3_access_secret. |
| s3_recordings_bucket | "" | S3-like bucket name to upload the video files of recorded sessions. Requires s3 credentials: s3_access_key, s3_access_secret, s3_endpoint_url |
Sounds and notifications
| Option | Default | Description |
|---|---|---|
| start_muted | false | Start the session with muted microphones for all participants. |
| notifications_enabled | true | Enable in-session notifications. |
| sounds_enabled | true | Enable sound for in-session notifications. |
| notification_position | "bottom-right" | Position of in-session notifications on the screen. |
Button appearance
| Option | Default | Description |
|---|---|---|
| hide_support_button | false | Do not show the default support button. This option is used in combination with shake_to_start or key_combo_to_start. |
| language | 'en' | Language of the interface. Available languages are: 'cs', 'de', 'en', 'es', 'et', 'fi', 'fr', 'hi', 'it', 'ja', 'ka', 'ko', 'nb', 'nl', 'pl', 'pt', 'ro', 'ru', 'sr', 'sl', 'sv', 'tr', 'vi', 'zh-hant' |
| support_button_position | 'bottomleft' | Position of the support button on the page. |
Control switching
| Option | Default | Description |
|---|---|---|
| host_switching_allowed | true | Enable host switching functionality |
| participants_can_request_to_interact | true | Enable tab control switching functionality |
Tabs
| Option | Default | Description |
|---|---|---|
| new_urls_allowed | true | Allow participants to open new tabs. If set to false, nobody in the session can open new tabs. |
| non_hosts_can_open_tabs | true | Allow all participants to open tabs. If set to false, only the host is allowed to open tabs. |
Developer console
| Option | Default | Description |
|---|---|---|
| verbose_console | true | Show more messages in browser console. |
Other
| Option | Default | Description |
|---|---|---|
| csp_report_uri | "" | The URI of the CSP report endpoint. |
Session Appearance
| Option | Default | Description |
|---|---|---|
| hide_cursors | false | Hide cursors and disable drawing for everyone but the in-control participant. |
| hide_session_ui | false | Hide the user interface, including the top bar, side bar, and notifications. |
Enterprise options
| Option | Default | Description |
|---|---|---|
| white_label | false | Hide Surfly branding in the interface of the session. |
| blocklist | "[]" | Restrict access to the specific resources. Example: [{"pattern": ".*example\\.com.*"}] |
| allowlist | "[]" | Allow access only to the specific resources. Example: [{"pattern": ".*example\\.com.*"}] |
| soft_session_end | false | When a session ends, keep the session open for the active tab's owner. This is used with soft_end_filter. |
| soft_end_filter | [] | For Surfly sessions started with JS API that persist even after they end, specify which domains a user can access from within the completed session. Specify a JSON array, e.g. ["example.com", "surfly.com"]. This option works together with soft_session_end. |
| localhost_requests_allowed | false | Allow pages to make requests to localhost (127.0.0.1). |
More information on restrictions
Audit log options
See our audit log documentation for more information about this functionality.
| Option | Default | Description |
|---|---|---|
| chat_logs_enabled | false | Keep a log of messages sent in the text chat during a session. (Note: text chat logs are stored in a .txt file.) |
| audit_logs_enabled | false | Enable session (audit) logs. Files are stored in the S3 compatible bucket. Permanent spaces will have one file per session. s3 access key and access secret must also be provided. |
| s3_access_key | "" | S3 access key (Note: all S3-compatible services are supported.) |
| s3_access_secret | "" | S3 secret access key (Note: all S3-compatible services are supported.) |
| s3_audit_log_bucket | "" | AWS S3 bucket name for session logs |
| s3_endpoint_url | "https://s3.amazonaws.com/" | S3 endpoint URL. When setting up AWS S3, make sure to accurately specify the endpoint URL for the S3 API, ensuring it points to the region of the bucket. For example https://s3.us-west-2.amazonaws.com. Please refer to the official AWS documentation here. (Note: all S3-compatible services are supported.) |
Session start
| Option | Default | Description |
|---|---|---|
| session_autorestore_enabled | true | Automatically try to restore sessions started with JS API on page reload. |
| hide_support_button_when_unavailable | true | Hide the support button when no agent is available |
| block_until_agent_joins | true | When a session is started using JS API, show the session URL and PIN until another participant joins. (Note: this option does not affect permanent Spaces.) |
| chat_integration | "disabled" | Enable Surfly integrations within the selected 3rd-party chat solution. |
| session_start_confirmation | false | Ask users for their consent before starting a session using JS API. |
| format_session_id | true | Use a series of three three-digit numbers (e.g. 123-456-789) as a session ID for temporary Spaces. (Note: this option does not affect permanent Spaces.) |
| hide_until_agent_joins | false | When a session is started using JS API, hide the session interface until another participant joins. (Note: this option does not affect permanent Spaces.) |
| language | "en" | Language of the interface |
| private_session | false | Only followers who are logged in and belong to the company which initiated the session can join |
| password_required | false | Require a password to join the session. The password can be found in the invite modal or in an invitation email. |
| admission_enabled | false | Prevent users from joining sessions until the host admits them. If set to false, users can join the session without admission. (Note: users can never join permanent Spaces without being admitted.) |
| region | "" | Use servers in this region to start sessions. If no servers are available in this region, the session will start in the next closest region. |
| selected_regions | "[]" | Use servers in these regions to start sessions. If no servers are available in these region, the session will not start. If none are selected, the session will start in any available region. To de-select a region, click while holding Ctrl. |
| shake_to_start | false | Allow users to start a session on pages with the support button, by shaking their mobile device. |
| start_with_loading_screen | true | Show a loading screen after a session is started. |
| start_with_invite_modal | true | When a session is started, show a modal that lets users invite participants to the session. Even if this option is false, sessions started from the dashboard will always show this modal. If block_until_agent_joins is set to true, sessions will never show this modal. The invite modal is always shown on outbound sessions, and never shown if block_until_agent_joins is enabled. |
| start_with_chat_open | false | Start sessions with the right sidebar open. (Note: the right sidebar contains text chat.) |
| key_combo_to_start | true | Allow users to start a session on pages with the support button by pressing Ctrl+Enter. |
| url | current page | Initial URL that will be opened inside the session. Only available in REST API at the moment |
| url_mangling | false | Generate unique in-session domains per session. This feature is typically used to enhance user privacy by generating unique cookie storage for each session on each domain, preventing user tracking. |
| alternative_proxy_enabled | false | Route all session traffic through a specific forward proxy. The proxy uses volatile storage and mimicks the behavior of a real web browser to bypass bot protection measures. This experimental option may decrease performance and cause issues. |
Session invitations
| Option | Default | Description |
|---|---|---|
| default_invitations_enabled | true | Send session invitations based on default Surfly templates. Custom invitations can be created using webhooks. |
| invitations_allowed | true | Allow participants to invite others to an ongoing session. |
Content manipulation
| Option | Default | Description |
|---|---|---|
| native_selects | true | Use the browser's native implementation for <select> elements. If set to false, Surfly's own implementation will be used. |
| hide_element_by_selector | "" | Hide elements matching this CSS selector from others. You can use ' *' to include all nested elements. |
File downloads
| Option | Default | Description |
|---|---|---|
| download_trigger_enabled | true | When a user downloads a file in a Surfly session, offer to let others download the file. If set to false, downloaded files will not be available to other participants. |
Canvas synchronisation
| Option | Default | Description |
|---|---|---|
| follower_drawing_selector | "" | Allow participants to draw on a canvas element with this CSS selector. This is used for electronic signatures (e-sign). (Note: to use this feature, participant needs to have permission to control the tab.) |
Browser native override
| Option | Default | Description |
|---|---|---|
| native_dialogs_enabled | false | Enable native dialogs—such as alert, confirm and prompt—during the session. (Note: unless a user dismisses these dialogues, sessions in temporary Spaces will automatically end after a period of time.) |
Cookies
| Option | Default | Description |
|---|---|---|
| embedded_sessions_only | false | When a user has 3rd-party cookies disabled in their browser, forbid them from starting a session using JS API. If set to false, sessions will open in a separate tab when 3rd-party cookies are disabled. (Note: this option does not affect permanent Spaces.) |
| cookie_transfer_enabled | true | When starting a Surfly session, transfer cookies (does not include httponly cookies), local storage, session storage and form fields from the original page opened in the browser into the Surfly session. When the Surfly session is ended everything (js cookies, local storage and session storage (except form fields)) is transferred back to the original webpage. |
| cookie_transfer_proxying | true | When starting a Surfly session, transfer httponly cookies between the Surfly session and the original page opened in the browser. This requires extra configuration; see our session-continuation guide for more information. |
| cookie_transfer_scopes | List of the cookie scopes that need to be transferred; see our session-continuation guide for more information. | |
| cookie_transfer_urls | List of session continuation points; see our session-continuation guide for more information | |
| enable_cookie_backtransfer | false | Transfer session cookies (including httponly cookies) back from the Surfly session to the original webpage. Enabling this option takes effect only when session-continuation is already set up and also requires to run Surfly from a domain that is same-site with the domain of the cookies intended to be transferred back. Check this article for more information on how to run Surfly from your own domain |
The cookie_transfer_scopes setting allows a fine-grained tuning of which cookies should be transferred. If specified, it should contain a list of JSON objects, each of them describing a single cookie using name, path, domain, and httponly properties:
cookie_transfer_scopes: [
{ name: 'shoppingcart', httponly: true, path: '/cart', domain: 'example.com' },
{ name: 'sessionid', httponly: false, path: '/', domain: '.example.com' },
];
The example above describes two cookies: shoppingcart, which is available on all pages under example.com/cart, and sessionid, which is set for all subdomains of example.com.
More information on session continuation
Privacy
Privacy options allow to hide information which is exposed on a client side, i.e. by a browser.
| Option | Default | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| privacy_user_agent | false | Mask data about the user's browser located in the Navigator object. This helps to protect against some malicious websites which abuse this feature to track users. | ||||||||||
| privacy_canvas | false | Prevent sites from reading the result of canvas drawing operations. This helps to protect against some malicious websites which identify users by drawing shapes and text on a user's webpage and noting the minor differences in the way they are rendered. Note: this can cause problems on sites which use Canvas elements legitimately. | ||||||||||
| privacy_date | false | Prevent sites from checking the local time on the user's computer or phone. This helps to protect against some malicious websites which abuse this information to uniquely identify users. Note: this can cause problems on sites which use Date legitimately. | ||||||||||
| privacy_devices | false | Prevent sites from reading detailed information about a client's devices, such as CPUs, memory, displays, battery and others. This helps to protect against some malicious websites which abuse this information to uniquely identify users. | ||||||||||
| privacy_embed | false | When this option is enabled, the "type" attribute of any of these elements will be changed to "text/surfly-blocked" if it is "application/x-shockwave-flash" or starts with "application/java-" or "application/x-java-". Additionally, the following attributes will be reset:
| ||||||||||
| privacy_ip_address | false | Hide a user's public ip address. This helps preserve user anonymity. If set to true, then the surfly-forwarded HTTP header is not added to requests, and WebRTC is disabled. Note: this can cause problems on sites which use WebRTC legitimately, like videochat applications. | ||||||||||
| privacy_beacon | false | Prevents sendBeacon POST request from being sent. This helps to protect against some malicious websites which abuse this feature to track users. Note: this can cause problems on sites which use this feature legitimately. | ||||||||||
| privacy_http_headers | false | When this option is enabled, the following headers will be set to a generic value:
|
Session end
| Option | Default | Description |
|---|---|---|
| follower_redirect_url | "" | When a session ends, redirect followers, who are not logged in to a custom URL. |
| leader_redirect_url | "" | When a session ends, redirect leaders to a custom URL. |
| end_of_session_popup_url | "" | URL of the page that will open in a popup window after the session ends. |
| end_redirect_enabled | true | Enable automatic redirects for sessions started with JS API. |
| anyone_can_deactivate_space | false | Allow terminating a session from the follower's end |
Group Option details
Here, you can find more detailed examples of the widget options that require specific syntax.
Blocklist and Allowlist format
A string representation of the JSON array is expected. Every element of the array is an object with the following properties:
pattern- regular expression. The requested url will be matched to this regular expression- (optional)
redirect- A url to redirect the user to. You can also specify the special{{referer}}pattern in the beginning of a redirect link, and that will be replaced by the Referer value at the moment of redirect. The user will be redirected to the page where they clicked the restricted link. - (optional)
type- restriction type. If present, and set to"all", restriction will be applied to all requests (otherwise restrictions affect only requests to top-level pages)
A blocked url is always added as a query parameter to the redirect url:
'http://mysite.com/restricted?blocked_url=https%3A%2F%2Fexample.com';
If a session was started with the Surfly button, and you want to end the
session when a user requests a restricted page, redirect them to the page
that includes widget.js and execute the following code:
Surfly.session().end(redirect_url);
endSession function will trigger the following events:
- session continuation
- end of the session
- leader is redirected to the page specified in
redirect_url
Blocklist example:
Restrict access to the website example.com. When the user tries to access
example.com they will be redirected to the default page provided by Surfly
{
"pattern": ".*example\\.com.*"
}
Allowlist example:
Allow access only to the example.com. When the user tries to access any other
website they will be redirected to the provided redirect url
{
"pattern": ".*example\\.com.*",
"redirect": "https://example.com/restricted"
}
Detecting a Surfly Session
You might want to change the behaviour of the website depending on whether it is a Surfly session or not. Example use cases are, for example, hiding a customized 'session start' button within the Surfly session, or to remove certain toolbars for a more aesthetic integration.
From within Javascript:
To detect a Surfly session from the client side, you can simply
check for the existence of a global variable called __surfly
For example, to hide a button within a Surfly session, you could implement the following:
if (window.__surfly) {
document.getElementById('session_start_button').display = 'none';
}
At the backend:
As all Surfly sessions will originate from our proxy servers, this could be used as a way to identify whether the request comes from Surfly or a client directly. However, we use different IP ranges for our proxy servers, and they also change over time, so we recommend a different way to do this.
On each session that comes through our proxy, we will add an 'surfly-forwarded' header that points to the original IP of the 'leader'.
When creating a request, you can also set the 'headers' option (in both the Javascript call and the REST call) to add additional headers. These headers can be used to, for example, add an "Authorization" header to allow to user to be logged in on your own backend or a custom header which can be used as an identifier. We will send these headers with each request made during the session.
Queue Behaviour Customization
Surfly comes with a relatively straightforward dashboard. We not only allow you to enrich the information presented on this dashboard but you can also completely build your own dashboard and integrate it in your own web application.
For example, if you have the widget added to a section of your web application where the user is required to be logged in, you probably have some knowledge about the user which might be useful to pass along to the agent. Information such as the user's name, email or even their phonenumber.
To make sure that this information becomes available in the dashboard you can
set userData to an object that provides these values as key, value pairs.
For example:
{
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+123123123123"
}
You can then pass this variable to the SurflySession.startLeader() function:
Surfly.session().startLeader(null, userData);
Of these key,value pairs, name and email will also be provided to the
Surfly session so that the session can display the name of the user in the
chatbox and make sure that the accompanying gravatar matches his email
address.