Skip to main content

The Surfly Object

Before you get started, you might want to freshen up on how. The main thing you would want to keep in mind is that co-browse sessions are opened in an iframe that lays on top of the original web page. So when we refer to being inside or outside a session, we refer to the Surfly iframe and the original web page respectively.

Surfly.isInsideSession​

Surfly.isInsideSession Boolean

Returns true if the current page is loaded within a Surfly session. This makes it possible to change the page behaviour while cobrowsing. Usually used together with currentSession

It allows you to detect whether the current page is loaded under Surfly, and also use the SurflySession API for communication with the outer window, as shown below:

if (Surfly.isInsideSession) {
  Surfly.currentSession.on('message', function (session, event) {
    if (event.origin === window.location.origin) {
      console.log('Outer window says:', event.data);
    } else {
      console.log("Outer window has a different origin");
    }
  });
}

Surfly.currentSession​

SurflySession Surfly.currentSession Object

If called from inside a session, this returns a SurflySession object referring to a session we are currently in. Otherwise, it returns null.

Tip

The same can be achieved by using Surfly.listSessions()[0]

Surfly.listSessions()​

Surfly.listSessions() Array 
Surfly.listSessions().forEach(function(session) {
  console.log('Found a session:', session.followerLink);
});

Returns a list of SurflySession objects that were created with JS API, or restored after the page reload. Note that by the time the init callback is called, this list can already contain some sessions restored after a page reload.

Inside a session, the return array will contain only one object, representing the currently open session (see Surfly.currentSession).

Surfly.on()​

Surfly Surfly.on( eventName String , callback Function )

Sets a global event handler.

If eventName is a session event, the handler will affect all sessions, including the currently created ones.

callback must be a function. Depending on the type of event, it will be provided with relevant data.

See Events section for more details.

Returns a reference to the Surfly object, so chained calls are possible:

Surfly.on(/*...*/).on(/*...*/);
Surfly.on('session_ended', function(session, event) {
  console.log('Session', session.followerLink, 'has just ended');
});

Surfly.agentAvailable​

Surfly.agentAvailable Boolean

Only available after Surfly has successfully been initialized (so after the readyCallback). Contains true if there is at least one company agent online.

// this is how you might hide a custom element depending on
// agent availability
var but = document.getElementById('my-custom-button');
if (!Surfly.agentAvailable) {
  but.style.display = 'none';
}
else {
  but.style.display = 'block';
}

The same can be established by using the agent_status event.

Surfly.session()​

SurflySession Surfly.session( [ sessionSettings Object ], [ sessionUrl String ] )

Creates a session object with provided settings. Some properties of the returned SurflySession may not be initialized. You can bind callbacks using .on() method to hook on specific points of session lifetime. Note that you will need to call .create() or .startLeader() / .startFollower() methods to actually create a session and open a cobrowsing window respectively.

sessionSettings: (optional) session settings object

sessionUrl: (optional) URL string with leader or follower session link. If specified, Surfly will not create a new session, and will just open the provided session link instead. This is useful, for example, when a session has been created beforehand using the REST API.

Surfly.init({widget_key: '**your key here**'}, function(init) {
  if (init.success) {
    if(!Surfly.isInsideSession){
      Surfly.session({start_with_chat_open: false}).startLeader();
    }
  }
});

Surfly.button()​

Surfly.button( [ settingsObject ] )

Adds a Surfly button to the current page. When a user clicks the Surfly Button, it will create a new Surfly session, and open a leader window. The Surfly button will automatically hide itself under the Surfly session, or if there is no support agent online (unless hide_support_button_when_unavailable is set to false).

settingsObject: here you can set settings that will be applied to all sessions created with this button. If there is a conflict, settings provided here will override the ones passed to Surfly.init().

Inside a session, there is no need to create a session, so Surfly.button() calls will be silently ignored.

The Surfly button is just a shortcut for a quick integration, and doesn't allow for much customization. For more fine-grained integration, use SurflySession API.

Surfly.init({widget_key: '**your key here**'}, init => {
  if (init.success) {
    Surfly.button({
        hide_support_button_when_unavailable: false,
        support_button_position: 'bottomleft'
    });
  }
});