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 (viewer_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.listAllSessions[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.giveControl()​

SurflySession.giveControl( clientIndex Integer )

(not available inside a session)

Switch control to the user with specified clientIndex. clientIndex is always 0 for the leader and 1 or more for followers.

See also Control options

SurflySession.requestControl()​

SurflySession.requestControl()

(not available inside a session)

Request control from the session leader. This call will be silently ignored if the user is already in control, if she is a leader, or if host_switching_allowed options is disabled.

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.pause()​

SurflySession.pause()

(not available inside a session)

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

SurflySession.resume()​

SurflySession.resume()

(not available inside a session)

Resume a session previously paused with pause()

SurflySession.resize() [deprecated]​

SurflySession.resize()

(not available inside a session)

This method is DEPRECATED and is ignored in Surfly v2.47 and newer. The viewport size is detected automatically inside iframes.

Set the size of the underlying session frame window to specified dimensions. Useful when the session is started with a custom frameSelector. Note that if you start a session without a custom selector, this function is called automatically every time you resize the browser window.

If width and height are omitted, the size of current browser window will be used.

session.setDrawingSettings({enabled: 'false', userIndex: 0});

Disables the leader's pen.

session.setDrawingSettings({timeout: 30, color: 'magenta'});

Sets everyone's pen color to magenta, and erases lines 30 seconds after they're drawn.

Surfly.listSessions()[0].setDrawingSettings({enabled: true, userIndex: 0})
Surfly.listSessions()[0].setDrawingSettings({enabled: false, userIndex: 0})

Toggles between leader's (userIndex: 0) cursor and drawing mode

SurflySession.toggleVideochatFullscreen()​

SurflySession.toggleVideochatFullscreen()

(not available inside a session)

Toggles videochat fullscreen mode

SurflySession.toggleVideochatMicrophone()​

SurflySession.toggleVideochatMicrophone()

(not available inside a session)

Mutes/unmutes your microphone

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)