Back to top

Basic Integration

In this quick start section, we’ll discuss three common use cases that you can implement out of the box. 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. 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.

<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(init) {
        if (init.success) {
        // display the default Surfly button
            Surfly.button();
        }
    });
</script>

If a customer starts a session from Web Application in iOS you will need to handle showing PIN by yourself using Surfly.isInsideSession flag and session_created event

Surfly.init(settings, function (initResult) {
        if (initResult.success) {
            if (!Surfly.currentSession) {
                Surfly.button();
            }
            if (Surfly.isInsideSession) {
                var infoel = document.getElementById("info");
                infoel.textContent = "In Surfly session";
                Surfly.on("session_created", function () {
                    infoel.textContent += ", pin:" + Surfly.currentSession.pin;
                });
            }
        }
    });


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 with an a link tag and add the #surflystart anchor to it:

<a href="#surflystart">Start a session</a>



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 stealth_mode 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 integrate Surfly with other chat solutions:


Intercom, Olark and Zendesk


If you make use of Intercom, Olark or Zendesk, we already have an integration ready for you. 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” or “zendesk”. You can then start co-browsing sessions directly from your chat solution’s dashboard by typing ^surfly. The session will start on your customer’s side, making them the leader, and the agent the follower. The agent can take the call from their Surfly queue page.


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).


First, we need to remove Surfly’s default chat box, which can be done by setting the Surfly option docked_only: true. Then 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.

Note: 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**', docked_only: true}, function(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.

Note: When you set settings through the JS API, these will take priority over the settings in the Surfly dashboard.

The most common UI elements that you might want to dive into further are:


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_docked false When enabled, the dock will be visible at the start instead of the chat widget. You can switch between both.
docked_only false When enabled, the Surfly chat widget will disappear and instead the dock will be displayed

Interface color: you can adjust this by setting the chat_box_color to a hex code that matches the color scheme of your website.

Option Default Description
chat_box_color #eb777f Color of UI (chatbox) elements inside the session

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
allow_control_switching true Disabling this option will make sure that the leader will always be the one in control and that control cannot be switched
agent_can_request_control false A follower can request control, after which it can be granted by the leader
agent_can_take_control false A follower can switch control without an explicit leader consent

Navigating to a new URL: this button allows your users to navigate to other websites.


Option Default Description
newurl true By disabling this option you will remove this button from the Surfly UI

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
newurl true By disabling this option you will remove this button from the Surfly UI

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 “” If this parameter is set, after the session ends the user will see a popup window with contents from the specified URL

A reference of all customizable options can be found in the Docs on the Session Options page: Session Options




Custom 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.


Basic landing 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

Generated by aglio on 14 Dec 2018