Skip to main content

Sessions

The Javascript API provides a set of functions allowing you to start and control the behaviour of your Surfly sessions.

Once a session has been initialized, you'll be able to use several events in order to check the session status and, if necessary, make modifications depending on this status. More information on how to handle events can be found on the session events page.

Starting sessions​

SurflySession SurflySession.startLeader( [ iframeSelector String ], [ userData Object ] )
SurflySession SurflySession.startFollower( [ iframeSelector String ], [ userData Object ] )

(not available inside a session)

Initialize a cobrowsing session, opening a new iframe/browser tab if necessary. Adds the session to the support queue.

iframeSelector - (optional) CSS selector string to an iframe element on the current page. If specified, Surfly will open a session in this iframe instead of creating a new one. Note that Surfly cannot open a session in an iframe when 3rd-party cookies are disabled. Also, this is not compatible with the open_in_new_window option.

userData - (optional) a plain object with additional data to be attached to the joining user. This will be visible in subsequent user-related events (participant_joined, for example), and can be used to track users when they join or leave the session. You are free to specify any type of data you want to pass to the method. Surfly offers three special fields that have additional effects:

  • name: this will be displayed as a user name in the Surfly chatbox inside a session
  • email: this will be used for Gravatar lookup
  • agent_id: will pin the (unpinned) session to a specific Agent. Agent must belong to the company owning the widget key that was used for creating the session.

userData from .startLeader() call will be visible on the Queue page in Surfly dashboard, so you can easily distinguish between the users in the queue.

Example:

var session = Surfly.session().startLeader();
// now send `session.followerLink` to someone else

// in another browser
Surfly.session({}, followerLink)
      .startFollower(null, {name: 'John Doe', foo: 'bar'});

SurflySession.create()​

SurflySession SurflySession.create()

(not available inside a session)

Just initialize a new session (retrieve a leader and follower links from Surfly server) without opening a cobrowsing window. In most cases there is no need to call this function explicitly. It will be called automatically from SurflySession.startLeader() and SurflySession.startFollower().

Note that you still must call SurflySession.startLeader() or SurflySession.startFollower() at some point, to open a cobrowsing window.

If the session is already initialized, SurflySession.create() does nothing.

SurflySession.end()​

SurflySession SurflySession.end( [ redirectUrl String ] )

Gracefully ends the current session (as long as the current user has permissions to do so).

If specified, redirectUrl should be a valid URL string. The user will be redirected there after the session ends. The exception is when end_of_session_popup_url settings is set. In this case, it will have priority over redirectUrl.

Note that by default a user is redirected to the page that was last visited inside the session.

SurflySession.settings​

SurflySession.settings Object

(read only, not available inside a session)

Returns the session settings with which the session was created

SurflySession.on()​

SurflySession SurflySession.on( eventName String, callback Function )

Use this to set an event handler. Inside the callback function, this will be set to the current SurflySession instance. See Events section for more details.

Returns a reference to the current SurflySession, so chained calls are possible:

Surfly.session().on(/*...*/).on(/*...*/).startLeader();

SurflySession.log()​

SurflySession SurflySession.log( entry Object )

Log custom message to the audit log. entry must be a plain JSON object. Can be used to track your user's steps during co-browsing. Handy for metrics and reveiling pain points on your website. The entry object can contain arbitrary keys, but there are several reserved keys with special meaning:

  • varN (where N is a number from 0 to 9): when provided, must have a String value. These variables can be referenced and used in visualization later on.

SurflySession.sendMessage()​

SurflySession.sendMessage( message Object, targetOrigin String )

This function is useful when you need to establish a communication channel between your JS code on the original page, and its proxified version inside the session.

It is available on both sides, and works in symmetric way: it will trigger a message event on the other side of the channel (see Events section).

message argument must be a plain JSON-serializable object. targetOriginshould be set to the origin of the expected recipient. If set to "*", message will be delivered regardless of the recipient's origin.

if (!Surfly.isInsideSession) {
  // From outside a co-browsing window, send a message to the co-browsing window
  var endBtn = document.getElementById('btn-end-queued-session');
  endBtn.addEventListener('click', function() {
    Surfly.listSessions()[0].sendMessage({message: 'end'}, window.location.origin);
  });
}
else {
// Check the cobrowsing session and set the message event listener
  Surfly.currentSession
  .on('message', function(session, event) {
    if (event.data.message === 'end') {
      // reply to the message
      sessionEnd();
    }
  });
}

SurflySession.openTab()​

SurflySession.openTab( url String )

(not available inside a session)

Open a new tab with specified url in the current session.

SurflySession.makeHost()​

SurflySession.makeHost( clientIndex Integer )

(not available inside a session)

Make the user with specified clientIndex the host of the session. clientIndex is always 0 for the leader and 1 or more for followers.

See also Control options

SurflySession.requestToHost()​

SurflySession.requestToHost()

(not available inside a session)

Request to host from the session leader. This call will be silently ignored if the user is already hosting, if they are a leader, or if host_switching_allowed option is disabled.

SurflySession.requestTabControl()​

SurflySession.requestTabControl()

(not available inside a session)

Request control over the tabs from the tab owner. This call will be silently ignored if the user is already controlling the tab, or if participants_can_request_to_interact option is disabled.

SurflySession.revokeTabControl()​

SurflySession.revokeTabControl()

(not available inside a session)

Revokes control over the tabs from the participant in control. This call will be silently ignored if the user is not the owner of the active tab, or if participants_can_request_to_interact option is disabled.

SurflySession.returnTabControl()​

SurflySession.revokeTabControl()

(not available inside a session)

Returns control over the tabs to the active tab owner. This call will be silently ignored if the user is not in control of the active tab, or if participants_can_request_to_interact option is disabled.

SurflySession.transferTabControl()​

SurflySession.transferTabControl( clientIndex Integer )

(not available inside a session)

Transfers control of your tabs to a user with specified 'clientIndex'. clientIndex is always 0 for the first tab_owner and 1 or more for the other participants.

SurflySession.getParticipants()​

SurflySession.getParticipants()

(not available inside a session)

Async method, which returns a list of session participants. Each participant object contains the following fields: name, email, online, client_index.

SurflySession.getTabs()​

SurflySession.getTabs()

(not available inside a session)

Async method, which returns a list of opened tabs in session participants.

SurflySession.activateTab()​

SurflySession.activateTab( ssid Integer )

(not available inside a session)

Method, which activates tab with certain ssid. ssid value could be found in the response of SurflySession.getTabs() method.

SurflySession.uploadFile()​

SurflySession.uploadFile()

(not available inside a session)

Method, which uploads a file to the session and must be triggered by a button click, as opening the file dialog requires a user gesture due to browser security restrictions.

SurflySession.relocate()​

SurflySession.relocate( newUrl String, newTab Boolean )

(not available inside a session)

Navigate current tab to newUrl, which must begin with a protocol, such as https://. If newTab is set to true, the link will open a new virtual tab inside the session window.

SurflySession.pauseTabs()​

SurflySession.pauseTabs()

(not available inside a session)

When called from the tab owner side, pause streaming content to other participants

SurflySession.resumeTabs()​

SurflySession.resumeTabs()

(not available inside a session)

Resume streaming content previously paused with pauseTabs()

SurflySession.toggleVideochatFullscreen()​

SurflySession.toggleVideochatFullscreen()

(not available inside a session)

Toggles videochat fullscreen mode

SurflySession.toggleVideochatMode()​

SurflySession.toggleVideochatMode('sidebar')

(not available inside a session)

Toggles videochat mode. The available modes are floating and sidebar

SurflySession.toggleVideochatMicrophone()​

SurflySession.toggleVideochatMicrophone()

(not available inside a session)

Mutes/unmutes your microphone

SurflySession.toggleDrawing()​

SurflySession.toggleDrawing()

(not available inside a session)

Toggles your drawing mode. Available only if you are in control of the active tab.

SurflySession.startScreensharing()​

SurflySession.startScreensharing()

(not available inside a session)

Start screensharing only for desktop. Available if screensharing_enabled option is enabled.

SurflySession.started​

SurflySession.started Boolean

(not available inside a session)

boolean, set to true if the session window is opened

SurflySession.leaderLink String

(not available inside a session)

contains a leader link. This is a URL that SurflySession.startLeader() opens. It can only be opened in one browser at a time.

SurflySession.followerLink String

(not available inside a session)

contains a URL that can be used for joining the session. This is a URL that SurflySession.startFollower() opens.

SurflySession.pin​

SurflySession.pin String

contains a 4-digit PIN code that can be used to join the session. This becomes available only after the session is started (either manually by .startLeader() call, or automatically by Surfly Button).

SurflySession.node​

SurflySession.node HTMLIFrameElement

(not available inside a session)

if a session is opened in an iframe, it contains a reference to its DOM node

SurflySession.window​

SurflySession.window Window

(not available inside a session)

reference to the session window (either tab window or contentWindow of the iframe container)