Session Events

Certain actions that happen within the session will trigger an event which can be tied to a certain Webhook defined by you.

But this can be extended further by yourself by leveraging our Virtual Web Extension API, allowing you to listen to certain Session events, such as when a session is started or the participant navigates to a new page. Next to that, each Session spins up its own Session API, such as: End the Session, Navigate to a Location, Load a Piece of Code, Send an API Message to Space Session

Use Cases

🚀 Use-Case: Enforcing Secure, Time-Limited Access to Premium Content

Getting Started

See the Session API reference for more information.

You can listen to and attach custom handler functions to events using webfuseSession.on(). Callback functions are provided with arguments, depending on the event type.

Session event handlers can be set with the webfuseSession.on() method, or with the global webfuse.on() method available from the Widget API. The latter will affect all existing and future sessions.

Callback functions should accept two arguments:

A Session instance that Triggers the event
A JSON object with event attributes

// This will be Triggers for all sessions, including the restored ones
webfuse
    .on('session_ended', session => {
        console.log(session, 'has ended');
    });

webfuse
    .initSpace('your_widget_key', 'your_space_id').then(async space => {
        const session = space.session();

        // Add event listeners
        session.on('session_started', session => {
            console.log('Session has started');
        });

        session.on('participant_joined', (session, event) => {
            console.log('A participant joined with client index:', event.clientIndex);
        });

        session.on('session_ended', session => {
            console.log('Session has ended');
        });

        // Start the session
        await session.start();
    });

`session_created`

Triggers when a session is created (usually after space.session() call).

`session_started`

Triggers when a session window has been loaded (usually after a call to session.start();). Has no additional parameters.

`session_ended`

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

Parameters

final_location

On the leader side, URL of the last browsed page.

`metadata_updated`

Triggers when the session metadata is updated.

Parameters

metadata

Object with the updated metadata values.

`message`

Triggers when the message is received.

Parameters

data

Message object sent from the other side.

origin

The origin of the sender window.

`host_rights_requested`

Triggers when host rights for the session had been requested.

Parameters

clientIndex

Index of the user who requested control.

`host_rights_refused`

Triggers when host rights for the session had been refused.

Parameters

clientIndex

Index of the user whose request was refused.

`host_changed`

Triggers 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.

`file_downloaded`

Triggers 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.

`chat_message`

Triggers when a message is received from the chat.

Parameters

message

Message received from the chat.

clientIndex

Index of the user who sent the message

`screen_resized`

Triggers every time the screen size of the session is changed.

Parameters

width

The width of the screen.

height

The height of the screen.

Participant Events

`participant_joined`

Triggers when a participant joins the session.

Parameters

clientIndex

Index of the user. Can be used in subsequent session.makeHost() calls.

userData

Data provided in userData argument of session.start*() call.

`participant_left`

Triggers when a participant leaves the session.

Parameters

clientIndex

Index of the user.

userData

Data provided in userData argument of session.start*() call

`user_activity`

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

Tab Events

`tab_opened`

Triggers when a new tab with url is opened via session.openTab() api call.

Parameters

url

Absolute URL of the new tab.

ssid

SSID of the opened tab.

`page_info`

Triggers when the page info is received from the cobrowsing session frame.

Parameters

title

The title of the page.

tabId

SSID of the tab.

`new_tab_opened`

Triggers when a new tab page is opened.

`tab_closed`

Triggers when a tab is closed.

Parameters

ssid

SSID of the closed tab.

`tab_relocate_start`

(not available inside a session)

Triggers when the current tab inside a virtual session starts loading a new page. In conjunction with the tab_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

ssid

SSID of the tab that is starting to load a new page.

`tab_relocated`

(not available inside a session)

Triggers when a tab is relocated to a new url. Not available for media sharing tabs (screen sharing, video camera sharing).

Parameters

url

Absolute URL of the new location.

ssid

SSID of the relocated tab.

`tab_reloaded`

Triggers when a tab reload is triggered. Not available for media sharing tabs (screen sharing, video camera sharing).

Parameters

url

Absolute URL of the new location.

ssid

SSID of the reloaded tab.

`tab_paused`

Triggers when a tab is paused by the tab owner. See also tab_resumed event.

Parameters

leaderIndex

Index of the participant who owns the tab.

ssid

SSID of the paused tab.

`tab_resumed`

Triggers when a session is resumed after a pause. See also tab_paused event.

Parameters

leaderIndex

Index of the participant who owns the tab.

ssid

SSID of the resumed tab.

`tab_activated`

Triggers when a tab is activated by any means, such as a session tab click or a session.activateTab() API call — including a click on the already-active tab, so the event may fire even when the active tab does not change.

Parameters

ssid

SSID of the activated tab.

`tab_control_requested`

Triggers when control over the tab has been requested.

Parameters

clientIndex

Index of the user who requested control.

ssid

SSID of the tab that control has been requested for.

`tab_control`

Triggers when control over the tab has been transferred.

Parameters

leaderIndex

Index of the participant who owns the tab.

controlIndex

Index of the participant who controls the tab at the moment.

ssid

SSID of the tab that control has been transferred for.

`huddle_mode`

Triggers when huddle mode is toggled.

Parameters

enabled

Status of huddle mode (boolean).

`huddle_follow`

Triggers when a when a participant follows another participant. This event is only trigged when huddle mode is enabled.

Parameters

client_index

Index of the follower.

following_index

Index of the parcipant the client_index is following.

`error`

(not available inside a session)

Triggers 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.

`popup_enabled`

Triggers when the extension popup is enabled.

Parameters

extensionId

ID of the extension that enabled the popup.

tabId

ID of the tab that the popup is enabled for. null if the popup is enabled for all tabs.

`popup_disabled`

Triggers when the extension popup is disabled.

Parameters

extensionId

ID of the extension that disabled the popup.

tabId

ID of the tab that the popup is disabled for. null if the popup is disabled for all tabs.

`popup_badge_text_set`

Triggers when the badge text of the extension popup is set.

Parameters

extensionId

ID of the extension that set the badge text.

text

The text to set as the badge text.

tabId

ID of the tab that the badge text is set for. null if the badge text is set for all tabs.

`popup_badge_background_color_set`

Triggers when the background color of the extension popup badge is set.

Parameters

extensionId

ID of the extension that set the background color.

color

The background color to set as the badge color.

tabId

ID of the tab that the background color is set for. null if the background color is set for all tabs.

`popup_title_set`

Triggers when the title of the extension popup is set.

Parameters

extensionId

ID of the extension that set the title.

title

The title to set as the popup title.

tabId

ID of the tab that the title is set for. null if the title is set for all tabs.

`popup_icon_set`

Triggers when the icon of the extension in the top bar is set.

Parameters

extensionId

ID of the extension that set the icon.

icon

The url of the icon that is set as the extension icon.

tabId

ID of the tab that the icon is set for. null if the icon is set for all tabs.

`popup_set`

Triggers when the popup of the extension is set.

Parameters

extensionId

ID of the extension that set the popup.

popup

The url of the popup that is set as the extension popup.

tabId

ID of the tab that the popup is set for. null if the popup is set for all tabs.

`extension_side_panel_opened`

Triggers when the extension side panel is opened.

Parameters

extensionId

ID of the extension that opened the side panel.

tabId

ID of the tab that the side panel is opened for. null if the side panel is opened for all tabs.

`extension_side_panel_closed`

Triggers when the extension side panel is closed.

Parameters

extensionId

ID of the extension that closed the side panel.

tabId

ID of the tab that the side panel is closed for. null if the side panel is closed for all tabs.

`extension_side_panel_options_set`

Triggers when the options of the extension side panel are set.

Parameters

extensionId

ID of the extension that set the side panel options.

options

The options that were set. options object contains the following properties:
- path: The path to the side panel template file relative to the root folder of the extension directory.
- enabled: Whether the side panel is enabled.
- tabId: ID of the tab that the side panel options are set for. null if the side panel options are set for all tabs.

tabId

ID of the tab that the side panel options are set for. null if the side panel options are set for all tabs.

`extension_side_panel_layout_set`

Triggers when the layout of the extension side panel is set.

Parameters

extensionId

ID of the extension that set the side panel layout.

side

The side of the extension side panel that was set. It must be either left or right, default is right.

tabId

ID of the tab that the side panel layout is set for. null if the side panel layout is set for all tabs.

`extension_side_panel_behavior_set`

Triggers when the behavior of the extension side panel is set.

Parameters

extensionId

ID of the extension that set the side panel behavior.

openPanelOnActionClick

Whether the side panel should be opened on action click. Default value is false.

`extension_refreshed`

Triggers when an Extension is refreshed in the Session.

Parameters

extension_id

ID of the Extension that was refreshed.

`extension_removed`

Triggers when an Extension is removed from the Session.

Parameters

extension_id

ID of the Extension that was removed.

Session UI Events

These events fire when a built-in session UI panel or dialog is opened or closed, whether triggered through the Session API ui namespace or by the user.

`chat_sidebar_opened` / `chat_sidebar_closed`

Triggers when the chat sidebar is opened or closed.

`videochat_sidebar_opened` / `videochat_sidebar_closed`

Triggers when the video chat sidebar is opened or closed.

`participants_sidebar_opened` / `participants_sidebar_closed`

Triggers when the participants sidebar is opened or closed.

`viewport_control_opened` / `viewport_control_closed`

Triggers when the viewport control drawer is opened or closed.

`automation_inspector_opened` / `automation_inspector_closed`

Triggers when the Automation Inspector panel is opened or closed.

`space_editor_opened`

Triggers when the space editor is opened.

Parameters

menu

The active editor menu (settings, extensions, apps, or access), or null.

tab

The active settings tab, or null.

`space_editor_closed`

Triggers when the space editor is closed.

`invite_dialog_opened` / `invite_dialog_closed`

Triggers when the invite dialog is opened or closed.

`video_settings_opened` / `video_settings_closed`

Triggers when the video settings dialog is opened or closed.

`end_dialog_opened` / `end_dialog_closed`

Triggers when the end-session confirmation dialog is opened or closed.

`videosharing_settings_opened` / `videosharing_settings_closed`

Triggers when the video sharing settings dialog is opened or closed.

Videochat Events

These events fire when the videochat state changes, whether triggered through the Session API or by the user.

`videochat_started`

Triggers when the videochat is started.

`videochat_camera_toggled`

Triggers when the camera is turned on or off.

Parameters

camera

The new camera state (true if on).

`videochat_microphone_toggled`

Triggers when the microphone is muted or unmuted.

Parameters

microphone

The new microphone state (true if on).

`videochat_fullscreen_toggled`

Triggers when videochat fullscreen mode is toggled.

Parameters

fullscreen

The new fullscreen state (true if fullscreen).

`videochat_mode_changed`

Triggers when the videochat mode changes.

Parameters

mode

The new mode (sidebar or floating).

`videochat_floating_position_changed`

Triggers when the floating videochat window is moved.

Parameters

x / y

The new top-left position of the floating videochat window, in viewport pixels.

`screensharing_started` / `screensharing_stopped`

Triggers when screensharing starts or stops.