Basic Integration
In this quick start section, we'll discuss three common use cases that you can
implement out of the box with our JavaScript API. The code examples below can be
copy-pasted into your html, what is left for you is to add your Surfly widget
key. If you want to customize your co-browsing flow, go to Settings -> Options
to easily enable or disable features from there.
Quick Start
Surfly can be integrated in many different ways to become a part of your desired flow, but first let's start with the basics.
You can easily offer Co-browsing sessions to visitors on your website by adding our default 'Get live help' button. The setup is simple, just add a button and script (see the snippet below) to your page, then add your domain to the domain list in the dashboard settings. Now you're ready to use our 'Get live help' button to better assist your customers.
When a customer sees the button, they can click on it to request help from an agent. By default, the button will only appear when you have an available agent, so don't worry about missing requests!
After clicking the button a Co-browsing session starts, and the user can share the session link. Your agent will see this request in the Surfly dashboard, and can then start a Co-browsing session by taking the call from their queue page.
Default button example
<script>
// this is a surfly snippet
(function(s,u,r,f,l,y){s[f]=s[f]||{init:function(){s[f].q=arguments}};
l=u.createElement(r);y=u.getElementsByTagName(r)[0];l.async=1;
l.src='https://surfly.com/surfly.js';y.parentNode.insertBefore(l,y);})
(window,document,'script','Surfly');
Surfly.init({widget_key:"**your widget key here**"}, function(initResult) {
if (initResult.success) {
// display the default Surfly button
if (!Surfly.isInsideSession) {
Surfly.button();
}
}
else {
console.log("Surfly was unable to initialize properly.")
}
});
</script>
It is important to keep in mind that Surfly needs to be able to reach the server over the network. You can use tools such as ngrok.io or burrow.io to allow Surfly access to your local machine whilst you are developing locally. However, if you really want to work on an isolated LAN, we can set up a special server for you. If you want to have your own local solution, please feel free to contact us at info@surfly.com
State transfer
When a Surfly session is started using the JavaScript API the state of the website will be transferred into the session.
This means that the JavaScript API will atempt to retrieve everything from your website's storage and make it available inside the collaborative session in order to make the co-browsed version of the website be in the exact same state as it was before the session was started.
If you need to transfer httponly cookies to, for example, keep the login state
of the website, see the Session-Continuation guide.
In addition, there could be cases when the Surfly session is started while the
user is in the middle of filling a form. That's why the JavaScript API will also
retrieve all information it can find in <input>, <select> and <textarea>
elements and transfer them inside the session too.
More precisely, the JavaScript API will atempt to transfer:
- Local storage
- Session storage
- Cookies available in
document.cookie(be aware that metadata such aspathordomainmight not be maintained) - Form fields values
Session end
When the Surfly session is ended, the JavaScript API will by default navigate the browser's
tab to the url where the session ended in order to give the user a feeling of continuity.
This behavior may be disabled with end_redirect_enabled session option.
The navigation url can be also configured with leader_redirect_url or specified in SurflySession.end(url).
Custom button
With Surfly you can completely customize the look and feel of your co-browsing session, let's start by creating your own 'Get live help' button! Just create a custom button and add an onclick handler to it:
<button onclick= "Surfly.session().startLeader()">Start a session</button>
Custom button example
Stealth mode
Our stealth mode setting enables you to start co-browsing from your website by pressing Ctrl and Enter on your keyboard. This can be useful when you want to make Surfly invisible to your users.
To enable stealth mode, you need to enable key_combo_to_start option on the
Settings page, and use the same script as shown above. If you don't want to
have a Surfly button on your website you can simply remove Surfly.button();
from the script.
Integrate with custom chat solutions
There are two different ways to use Surfly together with other chat solutions:
- Through our built-in integration for Intercom, Olark, LiveChat and Zendesk
- Simple integration with other chat solutions
Intercom, Olark, LiveChat and Zendesk
If you make use of Intercom, Olark, LiveChat or Zendesk, we already have a chat feature ready for you that allows you to start co-browsing directly from your chat widget, by simply typing ^surfly.
Let's say your agent is talking to a customer through your Intercom chat widget. The customer is stuck on the website and needs help filling in a form. The agent suggests to join the customer in their browser and the agent starts the co-browsing session by typing ^surfly. The co-browse session starts on the customer's side, on the exact same webpage. A four number session ID is displayed to the customer, which can be communicated to the agent in order for them to identify the correct co-browse session from the Surfly queue.
To enable this feature, just add the above script from the "Basic integration" section to the page you want to be able to co-browse from, and enable the “Chat integration” option from your Surfly dashboard, or add it to the script by setting chat_integration to “intercom”, “olark”, “livechat” or “zendesk”. Click here for our video tutorial.
Other chat solutions
If you make use of a different chat solution, you have to make sure that you load their snippet within the Surfly script to avoid loading their chat widget twice (both on the original page and again within the Surfly session).
We add a condition to the end of the below script to make sure that a second chat window doesn't open when a Surfly session starts.
Then simply add the snippet of your chat solution in the script.
Now you'll be able to communicate with your customers without any disturbance, both inside and out of your co-browsing session.
When you integrate Surfly with another chat solution, the Z-index of the chat window might be lower than that of the Surfly co-browsing iframe. The Surfly iframe has a Z-index of 2147483547
You can use below example to integrate Surfly together with your third-party chat solution:
<script>
(function(s,u,r,f,l,y){s[f]=s[f]||{init:function(){s[f].q=arguments}};
l=u.createElement(r);y=u.getElementsByTagName(r)[0];l.async=1;
l.src='https://surfly.com/surfly.js';y.parentNode.insertBefore(l,y);})
(window,document,'script','Surfly');
Surfly.init({widget_key:'**your widget key here**'}, init => {
if (init.success) {
// display the default Surfly button
Surfly.button();
}
});
if(!Surfly.isInsideSession){
// Add your chat solution's snippet below
// ...
// End of chat snippet
}
</script>
UI customization options
The basic integration script above comes with default settings. When you log in to your Surfly account and go to "Settings" >> "Options" you can see which options are enabled or disabled. You can adjust these settings from the dashboard, but you can also update them by adding them to the above script.
When you set settings through the JS API, these will take priority over the value in the Options page of the Surfly dashboard
The most common UI elements that you might want to dive into further are:
Overall branding: The overall branding colors, logo, and dashboard background image can be modified to suit your brand. These options can be found under "Settings" >> "Options" >> "Company settings".
Please ensure that each of your chosen text colors significantly contrasts with the respective background color. White is usually a good choice for text on dark backgrounds; black is usually a good choice for text on light backgrounds.
| Option | Default | Description |
|---|---|---|
| Branding primary color | Surfly red | The main color for menus and buttons |
| Branding primary text color | White | The color for text on top of the primary color |
| Branding secondary color | Reddish brown | The hover color for menus and buttons, and for unselected text and icons |
| Branding secondary text color | White | The color for text on top of the secondary color |
| Branding logo | Surfly logo | A URL for a custom image to load in the top-left corner of the dashboard |
| Branding logo link | Surfly homepage | A custom URL that the user will be sent to when clicking the logo in the top-left corner of the dashboard |
| Dashboard background image | A mountain lake | A URL for a custom image to show in the background of the dashboard |
The dock: The dock contains buttons which you can use to control the co-browsing session. There are three ways in which you can customize the functionality of the dock. By default, the Surfly chat widget is visible at the start of the session, and the dock only appears when you minimize the chat.
| Option | Default | Description |
|---|---|---|
| start_with_chat_open | false | Start sessions with the right sidebar open. (Note: the right sidebar contains text chat.) |
Switching control: there are three ways to customize the flow of how control over the session can be switched between the users.
| Option | Default | Description |
|---|---|---|
| host_switching_allowed | true | Allow any participant to ask for host rights. Space Owner can take the Host rights at any time. |
Navigating to a new URL: this button allows your users to navigate to other websites.
| 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. |
Inviting other users to the session: by clicking this button, you would open a popup window that allows you to send a co-browse invite to others, or you can copy the co-browsing link instead.
| Option | Default | Description |
|---|---|---|
| invitations_allowed | true | Allow participants to invite others to an ongoing session. |
Popup at the end of the session: it can be very useful to add a popup at the end of the co-browsing session. It's a great way to get feedback from your users through a survey for instance.
| Option | Default | Description |
|---|---|---|
| end_of_session_popup_url | "" | URL of the page that will open in a popup window after the session ends. |
Confirmation modal body: Customize the body of the confirmation pop up
that is displayed when session_start_confirmation is set to true and the user
wants to start the session.
| Option | Default | Description |
|---|---|---|
| confirmation_modal_body | You've requested assistance and a secure co-browsing session will be prepared to facilitate this request. The agent that will assist you will not be able to see any open tabs in your browser or sensitive information such as passwords. Do you want to proceed to connect with the agent? | the body of the confirmation pop up |
A reference of all customizable options can be found in the Docs on the Session Options page.
Basic landing page
In the previous examples a customer would click on a button and then be placed in a queue. Alternatively, you can also create a landing page to start co-browsing from. You can guide your website visitors to this page, or you can easily send the URL to your clients. When someone visits this page, a co-browsing session automatically starts and the agent can join by taking the call from the queue. After the session starts, you can redirect to an existing page on your website, or you could for instance, also add this landing page functionality to a product demo page.
You can easily turn any page on your website into a landing page. Just
implement the Surfly initialization script on the page, and start sessions
directly by adding #surflystart to the end of the URL like
this: example.com/#surflystart