Skip to main content

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('viewer_joined', function(session, event) {
console.log('There are', event.count, 'users in total');
})
.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
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
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
control

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

  • to index of the client that now has the control. Always 0 for the leader, 1 or more for a viewer
  • gained set to true if control was given to the current user
  • myIndex contains the user index of the current user_activity
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.