Session API

The Webfuse Session API provides a set of functionality allowing you to start and control the behaviour of your Virtual Sessions.

There are three contexts to gain access to the Session API:

1. Via Widget – After having initialized a new Session using the Widget (browser.webfuse).
2. Via Extension – Within Extension script components (browser.webfuseSession).
3. From within the currently augmented application – Only properties and methods marked as public are available on the webfuse.currentSession namespace.

started

Returns true if the session window is opened.

webfuseSession.started: boolean

pin

Contains a 4-digit PIN code that can be used to join the session. This becomes available only after the session is started.

webfuseSession.pin: string

node

If a session is opened in an iframe, it contains a reference to its DOM node.

webfuseSession.node: HTMLIFrameElement

window

Reference to the Session window (either tab window or contentWindow of the iframe container)

webfuseSession.window: Window

General Functionality

relocate()

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.

webfuseSession.relocate(newUrl: string, newTab: boolean): void

uploadFile()

Uploads a file to the current Session which will be opened in a new tab. A file input element can be used to pass the file to the method.

webfuseSession.uploadFile(file: File): void

getSessionInfo()

Returns an object containing information related to the current Session and sends it to the widget and all Extensions in the Session:

webfuseSession.getSessionInfo(): void

{
    "sessionId": "<session_id>",
    "opentokSessionId": "<opentok_session_id>",
    "space": {
        "access_control": "public",
        "company_id": 1,
        "domain": "<space_domain>",
        "host_rights": "everyone",
        "id":  1,
        "identification": "anonymous",
        "is_paused": false,
        "link": "<space_url>",
        "name": "test",
        "slug": "test",
        "type": "meeting",
        "visibility": "members-only"
        "adminIds": [9, 1],
        "memberIds": []
    },
    "metadata": {
        "foo": "bar"
    }
}

end() public

Gracefully end the current Session (as long as the current user has permissions to do so).

webfuseSession.end(redirectUrl?: string): void

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.

Audit Functionality

log() public

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.

webfuseSession.log(entry: object):

Reserved Keys

varN

• (where N is a natural number from 0 to 9) when provided, must have a string value. These variables can be referenced and used in visualization later on.

takeScreenshot()

Async method which uses browser native API to take screenshot of a page/window/screen. If successful sends an event to widget and Session Extensions with image data as ImageBitmap and returns same value.

webfuseSession.takeScreenshot(keepStreamOpened: boolean): Promise<ImageBitmap>

Parameters

keepStreamOpened

• If true allows to avoid permission request popup showing up on every call, until current stream track is closed manually by user (default true).

Returns

A promise that resolved to the screenshot image bitmap object.

Messaging & Event Handling

on() public

Use this to set an Event handler. Inside the callback function, this will be set to the current session instance.

webfuseSession.on(eventName: string, callback: (message: unknown) => void)

Returns a reference to the current session, so chained calls are possible:

const session = space.session();
session.on('session_started', session => {})

sendMessage() public

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.

webfuseSession.sendMessage(message: unknown, targetOrigin: string): void

It is available on both sides, and works in symmetric way: it will trigger a message event on the other side of the channel.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 (!webfuse.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 () {
        webfuse.listSessions()[0].sendMessage({ message: 'end' }, window.location.origin);
    });
} else {
    // Check the cobrowsing Session and set the message event listener
    webfuse.currentSession.on('message', function (session, event) {
        if (event.data.message === 'end') {
            // reply to the message
            sessionEnd();
        }
    });
}

broadcastMessage()

Broadcast a message to all participants in the Session which will be receivable by all Extension components.

webfuseSession.broadcastMessage(message: string): void

Parameters

message

• The message to broadcast.

sendChatMessage()

Send a message to the chat. Available if chat_enabled option is enabled.

webfuseSession.sendChatMessage(message: string): void

Parameters

message

• The message to send to the chat.

Tab Functionality

openTab()

Open a new tab with specified url in the current Session.

webfuseSession.openTab(url: string)

getTabs()

Returns a list of opened tabs in Session participants.

webfuseSession.getTabs(): Promise<object[]>;

Returns

A list of opened tabs in Session participants.

activateTab()

Activates tab with certain ssid. ssid value could be found in the response of session.getTabs() method.

webfuseSession.activateTab(ssid: number): void

pauseTabs()

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

webfuseSession.pauseTabs(): void

resumeTabs()

Resume streaming content previously paused with pauseTabs()

webfuseSession.resumeTabs(): void

## openNewTabPage()

Open the new tab page.It will either open the default new tab page or the Extensions new tab page if present

``` ts
webfuseSession.openNewTabPage(): void

Collaborative Functionality

getParticipants()

Returns a list of Session participants.

webfuseSession.getParticipants(): Promise<{
    name: string;
    email: string;
    online: boolean;
    client_index: number;
    self: boolean;
}[]>

self is a boolean value that indicates if the participant is the current user.

Returns

A list of Session participants.

toggleDrawing()

Toggles your drawing mode. Available only if you are in control of the active tab.

webfuseSession.toggleDrawing()

makeHost()

Make the user with specified clientIndex the host of the Session. clientIndex is always 0 for the leader and 1 or more for followers.

webfuseSession.makeHost(clientIndex: number): void

requestToHost()

Request to host from the Session Leader. This call will be silently ignored if the user is already hosting, if they are a leader, or if host_switching_allowed option is disabled.

webfuseSession.requestToHost(): void

requestTabControl()

Request control over the tabs from the tab owner. This call will be silently ignored if the user is already controlling the tab, or if participants_can_request_to_interact option is disabled.

webfuseSession.requestTabControl(): void

revokeTabControl()

Revokes control over the tabs from the participant in control. This call will be silently ignored if the user is not the owner of the active tab, or if participants_can_request_to_interact option is disabled.

webfuseSession.revokeTabControl(): void

returnTabControl()

Returns control over the tabs to the active tab owner. This call will be silently ignored if the user is not in control of the active tab, or if participants_can_request_to_interact option is disabled.

webfuseSession.returnTabControl(): void

transferTabControl()

Transfers control of your tabs to a user with specified ‘clientIndex’. clientIndex is always 0 for the first tab_owner and 1 or more for the other participants.

webfuseSession.transferTabControl(clientIndex: number): void

toggleHuddleMode()

Toggle huddle mode.

webfuseSession.toggleHuddleMode(): void

followParticipant()

Only when huddle mode is enabled. Follow the participant.

webfuseSession.follow_participant(clientIndex: number): void

Parameters

client_index

• Unique client index.

Videocall Functionality

toggleVideochatFullscreen()

Toggle videochat fullscreen mode.

webfuseSession.toggleVideochatFullscreen(): void

toggleVideochatMode()

Toggles videochat mode.

webfuseSession.toggleVideochatMode(mode?: 'floating' | 'sidebar'): void

Parameters

mode

• Designated mode (floating or embedded indie the sidebar).

toggleVideochatMicrophone()

Mute/unmute the local microphone.

webfuseSession.toggleVideochatMicrophone()

startScreensharing()

webfuseSession.startScreensharing(): void

Start screensharing only for desktop. Available if screensharing_enabled option is enabled.

Caution

This method requires a user gesture. It must be called from within an event handler triggered by user interaction such as a button click, key press, or other interactive element.