Events

Surfly JS API dispatches a number of events that you can listen to and attach custom handler functions using Surfly.on() and SurflySession.on(). Callback functions are provided with arguments, depending on the event type.

Global Events

Global events can be registered with Surfly.on() method.

Global event handlers will be provided with 2 arguments:

• a reference to the global Surfly object
• a JSON object with event attributes

// this will be triggered for all sessions, including the restored ones
Surfly.on('agent_status', function(api, event) {
  if (event.available) {
    console.log('There is an available support agent');
  } else {
    console.log('There is no support agents available at the moment');
  }
});

Available global events

agent_status

triggered when a support agent availability changes. Parameters:

• available is set to true if a support agent has just become available, and false if all agents have become unavailable.

session_restored

(not available inside a session)

triggered when a SurflySession object is recreated after a page refresh. This happens only when session_autorestore_enabled option is on.

Session Events

Session event handlers can be set with the SurflySession.on() method, or with the global Surfly.on() method. The latter will affect all existing and future sessions.

Callback functions should accept two arguments:

• a SurflySession instance that triggered the event
• a JSON object with event attributes

// this will be triggered for all sessions, including the restored ones
Surfly.on('session_ended', function(session) {
  console.log(session, 'has ended');
});

function startCobrowsing () {
  Surfly.session({start_with_chat_open: false})
    // these handlers will only be called for this particular session
    .on('session_started', function(session) {
      console.log(session, 'is fully initiated');
    })
    .on('participant_joined', function(session, event) {
      console.log('Participant ', event.clientIndex, 'joined the session');
    })
    .startLeader();
}

Available session events

session_created

triggered when a session is created (usually after SurflySession.create() call).

session_queued

(Deprecated: use session_created event instead) triggered when the session has been placed in the waiting queue, and the PIN code is generated

session_started

triggered when a session window has been loaded (usually after a call to SurflySession.startLeader()). Has no additional parameters.

session_loaded

triggered when the DOM inside the session has been fully loaded. Has no additional parameters.

viewer_joined

triggered when a follower joins the session. Parameters:

• count updated number of users in the session
• clientIndex index of the user. Can be used in subsequent SurflySession.giveControl() calls
• userData data provided in userData argument of SurflySession.start*() call

participant_joined

triggered when a participant joins the session. Parameters:

• clientIndex index of the user. Can be used in subsequent SurflySession.makeHost() calls
• userData data provided in userData argument of SurflySession.start*() call

viewer_left

triggered when a follower leaves the session. Parameters:

• count updated number of followers in the session
• clientIndex index of the user
• userData data provided in userData argument of SurflySession.start*() call

participant_left

triggered when a participant leaves the session. Parameters:

• clientIndex index of the user
• userData data provided in userData argument of SurflySession.start*() call

session_ended

triggered when the session has been properly finished (normally after clicking the close button, or as a result of SurflySession.end() call). Parameters:

• final_location On the leader side, URL of the last co-browsed page

message

triggered when the message is received. Parameters:

• data message object sent from the other side
• origin the origin of the sender window

user_activity

triggered when master clicks, moves mouse, or presses any key. Triggered once per second if activity is present.

relocate_start

(not available inside a session)

triggered when the current tab inside a Surfly session starts loading a new page. In conjunction with the relocated event, it allows you to track page loading inside a cobrowsing session. For example, use it to show a custom loading indicator. Parameters:

• url absolute URL loading webpage

relocated

(not available inside a session)

triggered when the current tab inside a Surfly session navigates to another page. Parameters:

• url absolute URL of new location

error

(not available inside a session)

triggered on common errors. Parameters:

• reason error description. Currently may be one of the following:
  • "other_connection" the leader_link was opened elsewhere. The new window/browser becomes the leader and the old leader is kicked out. It also happens if follower_link was open twice in the same browser
  • "connect_failed" The WebSocket connection to Surfly cannot be established
  • "create_failed" Surfly session could not be created. Check the details attribute of the event object for more information about the error
  • "start_failed" Surfly session could not be started. Check the details attribute of the event object for more information about the error

host_rights_requested

triggered when host rights for the session had been requested. Parameters:

• clientIndex index of the user who requested control

host_changed

triggered when host of the session has been changed. Parameters:

• to index of the client that now is the host. Always 0 for the leader, 1 or more for a viewer
• gained set to true if host rights were given to the current user
• myIndex contains the user index of the current user_activity

tab_control_requested

triggered when control over the tab has been requested. Parameters:

• clientIndex index of the user who requested control

tab_control

triggered when control over the tab has been transferred. Parameters:

• tabIndex index of the tab which control has changed
• leaderIndex index of the participant who owns the tab
• controlIndex index of the participant who controls the tab at the moment

file_download

triggered when a file download occurs inside the session. Note that this event is only fired when the user is controlling the session. This JS event is fired regardless of the download_trigger_enabled session option. Parameters:

• url direct link to the downloaded file. File will be available until the end of the session.
• filename name of the downloaded file

session_pre_end

(Supported only on the leader side)

triggered when a user tries to end the session using the "✕" button in the session UI. This can be used, for example, for storing the state of your page before ending a session. Note that this event is not fired if you end a session using JS API or REST API. WARNING: if you attach a listener for this event, you MUST eventually call SurflySession.end(), otherwise the session will not be ended. Parameters:

• final_location contains the URL of the last co-browsed page

session_paused

(Supported only on the leader side)

triggered when a session is paused by the leader. See also session_resumed event and the documentation on pause_enabled session option.

session_resumed

(Supported only on the leader side)

triggered when a session is resumed after a pause. See also session_paused event and the documentation on pause_enabled session option.

tab_paused

triggered when a tab is paused by the tab owner. See also tab_resumed event and the documentation on pause_enabled session option. Parameters:

• tabIndex index of the tab
• leaderIndex index of the participant who owns the tab

tab_resumed

triggered when a session is resumed after a pause. See also tab_paused event and the documentation on pause_enabled session option. Parameters:

• tabIndex index of the tab
• leaderIndex index of the participant who owns the tab