Back to top

Advanced integration


In the Basic Integration chapter, we gave you all the tools to get started with Surfly co-browsing. If you are looking into a more advanced integration, maybe because you want to add extra features to the basic Surfly flow, or because you want to add co-browsing to your CRM system, this next section will explain you how to add advanced functionalities.




Advanced landing page


You can also create a new page on your website to function as a lobby page. When someone visits this page, a co-browsing session starts and the session ID is displayed. When the agent joins the session, both users are redirected to a page you specify:

<html>
<body>
    <script>
        // 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');

        // The preferred way is to set session options from the Surfly web interface,
        // so in most cases you only need to provide a widget key below,
        // but you can also override any options here
        var settings = {
            widget_key: "**your widget key here**",
            hide_until_agent_joins: true,
            start_docked: true
        };

        // Surfly.init() must be called before any other API call
        Surfly.init(settings, function(init) {
        if (init.success && !Surfly.isInsideSession) {
            Surfly.session()
            .on("session_started", function(session, event) {
                // display the PIN of the current session
                document.querySelector("#sessidtarget").innerText = session.pin;
            })
            .on("viewer_joined", function(session, event) {
                // if the first viewer joins, redirect to a page of your choice
                if (event.count == 1) {
                session.relocate("www.surfly.com");
                }
            })
            .startLeader();
        }
        });
    </script>

    <h1>Landing Page Example</h1>
    Session Code: <span id="sessidtarget">...</span>
</body>
</html>



Customize your flow even more and wow both your users and agents with this advanced tutorial.


Session ID


Lets re-think how co-browsing sessions are started.


The session ID approach can be useful when there are many requests on a site, and the agent needs to easily identify the correct customer from their queue. At this point, the agent is generally already talking to the customer through chat or phone. The customer can confirm their ID with the agent, who will then pick up the corresponding call in their Surfly dashboard.


There are two ways to enable the display of this session ID.

The easiest way is to enable the block_until_agent_joins option in your session options. Otherwise, you can configure and customize your own session ID flow by using our built in session.pin call as explained in the code example below.




Start/End Popups


A pop up at the start of a session can be very useful in case you want to add a welcome message or terms of agreement to your flow.

So this is how the flow looks like:

  • The user clicks a custom “Get help” button

  • The modal appears showing the terms of agreement

  • When the user clicks “Agree”, a Co-browsing session starts

  • The session agreement disappears and shows the session ID, which the agent can use to identify the correct call from the queue

In the code example below, we start by adding the “Get help” button. Then we create the modal. It has two buttons, and on the “Agree” button, we call the sessionStart() function. We then add the Surfly options that fit our flow.

You can also add a popup to the end of the session, if you want to add a survey for instance. This is a useful way of getting feedback from the session.

We can use the end_of_session_popup_url option to point to the url of our survey page. Again, we add this as an option in the ‘settings’ variable.

You can also pass the url as a parameter in Surfly.session().end( [redirectUrl] ). However, the end_of_session_popup_url option has priority over this function.




Example code:


<html>
<head>
<style>

#btn-request-session {

}
#surfly-session-modal {
    position: absolute;
    margin: 200px 30%;
    background: lightcoral;
    padding: 10px;
    border-radius: 5px;
}
#session-agreement {

}
#session-id {

}
.hidden {
    display: none;
}
.modal-button {

}

</style>
</head>
<body>
    <h1>Co-browsing example</h1>
    <!-- Button that will trigger the popup -->
    <button id="btn-request-session" class="hidden">Get help</button>

    <!-- Create a popup -->
    <div id="surfly-session-modal" class="hidden">
        <h4>Welcome to co-browsing</h4>

        <!-- Add a session agreement the user has to agree to before co-browsing is initiated -->
        <p id="session-agreement">You are about to start a co-browsing session. By clicking "Agree" you allow the helpdesk agent to browse the website with you.</p>

        <!-- Placeholder for displaying the session PIN -->
        <p id="session-id"></p>

        <!-- Button to start the co-browsing session -->
        <button class="modal-button" id="btn-start-session">Agree</button>

        <!-- Cancel button is shown until the agent joins -->
        <button class="modal-button hidden" id="btn-cancel-session">Cancel</button>
    </div>

    <script>
    //Add the 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 session options, you need to provide your own widget key
    var settings = {
        widget_key: '**Insert your Widget Key here**',
        block_until_agent_joins: false,
        hide_until_agent_joins: true,
        start_docked: true,
        splash: false,
        end_of_session_popup_url: "https://example.com/survey"  // link to a survey page that will be shown after session end
    };

    // Initialize the JS API
    Surfly.init(settings, function(init) {
        if (init.success && !Surfly.isInsideSession) {
            // If API is initialized successfully, show the start button
            var startButton = document.querySelector("#btn-request-session");
            startButton.classList.remove('hidden');
            startButton.addEventListener('click', function() {
                // when a user clicks the start button, show the start popup
                var popup = document.querySelector('#surfly-session-modal').classList.remove('hidden');
            });

            // when the Agree button is clicked, start a co-browsing session
            document.querySelector('#btn-start-session').addEventListener('click', sessionStart);
        }
    });

    // sessionStart() is called when a user clicks the Agree button
    function sessionStart() {
        // hide the Agree button so that it cannot be clicked twice
        document.querySelector('#btn-start-session').classList.add('hidden');

        // Create a co-browsing session
        Surfly.session()
            // When the session is started, show the session PIN so that it can be passed to the helpdesk agent
            .on('session_started', function(session, event) {
                // display the session PIN
                var showId = document.querySelector("#session-id");
                showId.textContent = session.pin;

                // Display the Cancel button
                var cancelButton = document.querySelector("#btn-cancel-session");
                cancelButton.classList.remove('hidden');

                // If the Cancel button is clicked, end the session
                cancelButton.addEventListener('click', function() {
                    session.end();
                });
            })
            // Start the session immediately
            .startLeader();
    }
    </script>
</body>
</html>



Audit log


With our built in .log() function you can track your users’ actions throughout the co-browsing session. These instances will be saved in your session logs which can be retrieved through the REST API. You can log anything you want. Maybe you would like to know how long your customers have waited in the queue? Maybe you want to know when your users have downloaded a file?

<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 **'}, function(init) {
    if (init.success && !Surfly.isInsideSession) {
        // display the default Surfly button
        Surfly.button();  

        // apply audit log functionality
        var currentDate;

        // record the tiome when user is placed in the queue
        Surfly.on('session_queued', function(session, event) {
            currentDate = Date.now();
        });

        // when an agent joins, calculate and log the waiting time
        Surfly.on('viewer_joined', function(session, event) {
            var waitingTime = (Date.now() - currentDate) / 1000;
            session.log("Agent joined after " + waitingTime + " seconds")
        })

        // if a file is downloaded within a session, log this as well
        Surfly.on('file_download', function(session, event) {
            session.log("A file with the file name: " + "'" + event.filename + "'" + " was downloaded")
        })
    }
});
</script>



Integration with a CRM or Web Application


Customizing stripped UI


Let’s say you removed the UI to keep your styling consistent, but now you’re missing some desired functionality. With Surfly you can choose which UI elements you want to keep, and even change how they appear. In our example below we chose to create a custom exit session button to display after a stripped session has started.


Considering that it’s an exit button, we don’t want it to be shown when the customer isn’t in a session. Also, in this case we define a function that ends the Surfly session and redirects the user to a different page.


See snippet below:


<button class="button" id="exit_button" style="display: none" onclick="exitSession()">Exit session</button>

<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(settings, function(init) {
    if (init.success) {
      if (Surfly.isInsideSession) {
        // inside the session, show exit button
        document.getElementById('exit_button').style.display = "block";
      }
    }
  });

  <br />

  function exitSession(){
    Surfly.currentSession.end('https://example.com');
  }
</script>

Send metadata to Agent


Now that customers are queueing up to get support, maybe you want to pass some metadata about them to the agent before the session starts? This can be useful in case we want to provide the customer’s name to the agent, for example. We can do this by passing a metadata variable in our initialization function.


Take a look below as we pass some details about Rose:


<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');

  var metadata = {"name": "RoseF","email": "rose@example.com"};

  Surfly.init({widget_key: '**your widget key here**'}, function(init) {
    if (init.success) {
      Surfly.session().startLeader(null, metadata);
    }
  });
</script>

Please note: If the visitor to your website is logged in, the data passed as metadata could also be retrieved from their account information. You can do this by applying session continuation.




Running Surfly on your own domain


If you want to run Surfly on your own domain, we have to register you in our deployment system. Please contact us at support@surfly.com for more info.

Next, there are a couple of things you need:

  • The domain name under which the appliance should run

  • A certificate with complete certificate chain which is valid for domainname.com and *.domainname.com. including a private key.

Please note: a wildcard certificate is only valid for one level of sudomains. For example, the wildcard certificate *.cobrowsing.domainname.com is valid for ws.cobrowsing.domainname.com, but not for session.ws.cobrowsing.domainname.com_


Generated by aglio on 14 Dec 2018