Advanced integration

In the basic Integration tutorial, we gave you all the tools to get started with Surfly co-browsing. But Surfly is more than a co-browsing solution---it's a powerful and flexible middleware that can be used to interact with the web in exciting ways. Surfly power users constantly invent new ways to use our tools, and we support these creative integrations.

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 some advanced integration techniques.

Advanced landing page

Next to the basic landing page you can also create a 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,
            url: "https://www.surfly.com"
        };

        // Surfly.init() must be called before any other API call
        Surfly.init(settings, function(init) {
        if (init.success && !Surfly.isInsideSession) {
            Surfly.session()
            .on("session_created", function(session, event) {
                // display the PIN of the current session
                document.querySelector("#sessidtarget").innerText = session.pin;
            })
            .startLeader();
        }
        });
    </script>

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

Landing page example

Full featured custom session ID approach

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

Confirmation pop-up example

End of session survey example

Example code:

<html>
<head>
<style>
    #surfly-session-modal {
        position: absolute;
        margin: 200px 30%;
        background: lightcoral;
        padding: 10px;
        border-radius: 5px;
    }
    .hidden {
        display: none;
    }
</style>
</head>
<body>
    <h1>Custom ID 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: "**your widget key here**",
        block_until_agent_joins: false,
        hide_until_agent_joins: true,
        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_created", 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>

Here you'll find an example page with above code implemented.

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');
        var settings = {
            widget_key: "**your widget key here**",
            hide_session_ui: true,
        };
        Surfly.init(settings, function(initResult) {
          if (initResult.success) {
              if (!Surfly.isInsideSession) {
                  Surfly.button();
              }
              else if (Surfly.isInsideSession) {
                  // inside the session, show exit button
                  document.getElementById("exit_button").style.display = "block";
              }
          }
        });
    
      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>

Restrict session creation

You can restrict users' ability to create new sessions by not providing a widget key on your site when initializing the Surfly Javascript API with Surfly.init(). Without the widget key, sessions can only be created using the REST API with your private REST API key. The server making the REST API requests will be the only way to create sessions. This gives you more control over session creation, allowing for additional business logic, creating sessions in advance, additional session limits, etc.

Info

Because Surfly is primarily a co-browsing tool, most clients include the widget key on their site, as it allows Surfly to be integrated on your site without using the REST API.

Without the widget key, some functionality is restricted by design:

no new sessions may be created using the Javascript API;
agents are not informed when leaders join a session; and
agent status is not available to site users.

You may still connect to sessions created with the REST API by passing a leader link, follower link, or session ID.

Action	Normal behavior	Behavior without a widget key
Join a session by URL or ID	Allowed	Allowed
Create a session	Allowed	Forbidden
Enter a session as leader	Allowed	Allowed, but will not notify connected agents
Enter a session as follower	Allowed	Allowed
Check agent availability	Allowed	Forbidden

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.

About wildcards

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

Advanced landing page​

Full featured custom session ID approach​

Session ID​

Start/End Popups​

Integration with a CRM or Web Application​

Customizing stripped UI​

Send metadata to Agent​

Restrict session creation​

Running Surfly on your own domain​