Skip to main content

Quickstart

Load Surfly widget​

To use the Surfly JS API, you will first need to include our snippet on the webpages you want to be able to start co-browsing from:

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

This snippet loads the necessary Surfly JS libraries. Once it is there, the Surfly.init() function will be immediately available. Note that it is on you to make sure that you don't make any other API calls until readyCallback is called.

Tag managers

We advise against loading Surfly through a tag manager, since tag managers come with certain limitations. If your users have an ad blocker installed, you run the risk that it will block the tag manager also. This is a side effect of ad blockers, as many of them block the loading of scripts from third parties. This means that these ad blockers would block all Javascript loaded through the tag manager, not just Surfly's. Therefore, it is advisable to add any code snippet to the website directly

Initialize the API​

Surfly.init( settings Object, [ readyCallback Function ] )

This function must be called (just once per page) before any other API call is made. This initializes the environment for Surfly, the settings based on settings object, it tests required browser features, and passes the result to the readyCallback function.

The best practice is to call Surfly.init() immediately after the snippet code. It doesn't slow down the page load, so it can even be placed in the <head> section of your HTML.

Tip

The settings object should contain at least your widget_key. Surfly can be used without a widget key, but this will require use of the REST API and functionality will be restricted.

You can also customize the confirmation pop up body (when session_start_confirmation is set to true a pop up is shown to the user before starting the session) by passing confirmation_modal_body argument to the settings object. The value of this argument should be a string.

We load the Surfly widget code asynchronously, so that it doesn't slow down your page load. This also means that the Surfly API is not initialized immediately after the snippet code is executed. That's why it is important that you always start by calling Surfly.init(), and don't make any other API calls before readyCallback is called.

Please refer to our examples to see how the API should be initialized.

Implement a callback function​

readyCallback should be a function accepting one argument with the following structure:

{
  "success": true|false,
  "errorMsg": "<error message or null if no error occured>"
}

In addition to success check, you probably want to detect if the page is currently loaded under Surfly session by checking if Surfly.currentSession exists.

Add your domain to the list​

Log into your Surfly account. On your dashboard, go to "Settings" -> "Options" -> "General session settings" and add the domains you want to integrate Surfly on to the "Domain list". Use the following format: "*example.com" or "*.example.com" (for subdomains).

Example​

The following example initializes Surfly JS API and adds a Surfly button on the page:

  (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**',
    embedded_sessions_only: true
  };
  Surfly.init(settings, function(initResult) {
    if (initResult.success) {
      console.log('All good for happy cobrowsing!');
      // it is now safe to use API
      if (!Surfly.isInsideSession) {
        Surfly.button();
      }
    } else {
      console.log('Your browser lacks features required by Surfly');
    }
  });

For more examples of common use cases, see the Examples page