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

🔌Webfuse API

See the Session API and Session Events 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.

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_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

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

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

relocate

(not available inside a session)

Triggers when the current tab inside a virtual session navigates to another page.

Parameters

• url absolute URL of new location

tab_paused

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

Parameters

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

tab_resumed

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

Parameters

tabIndex

• Index of the tab.

leaderIndex

• Index of the participant who owns the tab.

tab_activated

Triggers when a tab is activated either by any means.

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.

tab_control_transferred

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

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.