Widget API

The Webfuse Widget is a small script module you can embed into any website with a few lines of copy-and-paste code. It works much like a Google Analytics tag. You only have to specify your own Widget Key, which you can generate in the Webfuse Studio application. Through the Widget, you can turn the usual website into the Webfuse-proxied counterpart only if needed. For example, if a user requires assistance after experiencing UI/UX friction.

The Widget API allows you to optionally render a Start Session button on top of the underlying website UI. When a user click this button, your website is loaded though the Wefbuse web proxy to, i.a, augment the page, collaborate on the page, or increase security measures.

The Widget API is a JavaScript API that becomes available in the window scope of the underlying website. The key functionality is: rendering the Widget Button to create a Session on click, or otherwise creating a Session programmatically.

Add the following snippet to relevant page;s of your web application (ideally within <HEAD>). It will load the Widget API under the globally available webfuse namespace.

(function (w, e, b, f, u, s) {
  w[f] = w[f] || {
    initSpace: function () {
      return new Promise(resolve => {
        w[f].q = arguments;
        w[f].resolve = resolve;
      });
    },
  };
  u = e.createElement(b);
  s = e.getElementsByTagName(b)[0];
  u.async = 1;
  u.src = 'https://{{DOMAIN}}/webfuse.js';
  s.parentNode.insertBefore(u, s);
})(window, document, 'script', 'webfuse');

webfuse.initSpace(
  '<WIDGET_KEY>',
  '<SPACE_ID>',
  {},
)
  .then(space => {
    console.log('Space:', space);
    console.log('Space ID:', space.id);
    console.log('Space slug:', space.slug);
  })
  .catch(error => {
    console.error('Failed:', error);
  });

The global webfuse object is the entry point for the Webfuse API. It provides methods to initialize and interact with Webfuse Spaces.

isInsideSession

Returns true if the current page is loaded within a Session. This makes it possible to change the page behavior while the page is being augmented. For example, if you have a web application and you want it to display different content when it is run within a Session you can check this property and change the behavior accordingly.

webfuse.isInsideSession: boolean

Example

if (webfuse.isInsideSession) {
    console.log('This page is running inside a Webfuse Session');
}

currentSession

Inside a Virtual Web Session, this returns a WebfuseSession object referring to the current Session. Otherwise, it returns null. It allows you to detect whether the current page is loaded under Webfuse, and also use the WebfuseSession API for communication.

webfuse.currentSession

Example

if (webfuse.isInsideSession) {
    webfuse.currentSession.on('message', function (session, event) {
        (event.origin === window.location.origin)
            ? console.log('outer window says:', event.data)
            : console.log("outer window has a different origin");
    });
}

initSpace()

Initializes a Space with the provided widget key and Space ID. This method must be called before any other API operations.

webfuse.initSpace(
    widgetKey: string,
    spaceId: string,
    integrationSettings?: {
        session_start_confirmation?: boolean;
        support_button_position?: string;
        hidden_support_button?: boolean;
        block_until_agent_joins?: boolean;
        hide_until_agent_joins?: boolean;
        key_combo_to_start?: boolean;
        shake_to_start?: boolean;
        session_autorestore_enabled?: boolean;
        metadata?: Record<string, string | number | boolean>;
    }
)

Parameters

widgetKey

Your Webfuse widget key.

spaceId

The ID of your Webfuse space.

[integrationSettings]

Integration settings:
session_start_confirmation Ask users for their consent before starting a Session using JS API.
support_button_position Position of the support button on the page.
hidden_support_button Do not show the default support button. This option is used in combination with shake_to_start or key_combo_to_start.
block_until_agent_joins When a Session is started using JS API, show the Session URL and PIN until another participant joins. (Note: this option does not affect permanent Spaces.)
hide_until_agent_joins When a Session is started using JS API, hide the Session interface until another participant joins. (Note: this option does not affect permanent Spaces.)
key_combo_to_start Allow users to start a Session on pages with the support button by pressing Ctrl+Enter.
shake_to_start Allow users to start a Session on pages with the support button, by shaking their mobile device.
session_autorestore_enabled Automatically try to restore sessions started with JS API when the page is reloaded.
metadata Object with key-value pairs that will be saved and then available in the Session information

Returns

A promise that resolves with a Space object when initialization is complete.

Example

webfuse.initSpace(
    '**your widget key here**',
    '**your space id here**',
    {
        block_until_agent_joins: true,
        metadata: {
            foo: 'bar'
        }
    }
)
.then(space => {
    console.log('Space initialized:', space.id);
})
.catch(error => {
    console.error('Failed to initialize space:', error);
});

listSessions()

Get a list of webfuse Session objects that were created, or restored after the page reload. Inside a Session, the returned array will contain only one object, representing the currently open Session.

webfuse.listSessions(): object[]

Returns

A Session object.

Example

webfuse.listSessions()
    .forEach(function(session) {
    console.log('Found a Session:', session.followerLink);
    });

on()

Defines a global event handler. If eventName is a Session Event, the handler will affect all Sessions, including the currently created ones.

webfuse.on(eventName: string, callback: (...data: unknown[]) => void)

Parameters

eventName

Name of a Session Event.

callback

A function to invoke when the event fires. Depending on the type of event, it will be provided with relevant data.

See Events section for more details.

Returns

A reference to the webfuse object, so chained calls are possible:

Example

webfuse
    .on(/*...*/)
    .on(/*...*/);

// Initialize Webfuse space and create a Session with event listeners
webfuse
    .initSpace('**your widget key here**', '**your space id here**')
    .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();
    }).catch(error => {
        console.error('Failed to initialize or start Session:', error);
    });

Space Object

The Space object is returned by webfuse.initSpace() and provides methods for creating Sessions and buttons within that space.

const space = await webfuse
    .initSpace('**your Widget Key here**', '**your Space IDd here**');

id

Get the space ID.

space.id: string

slug

Get the space slug.

space.slug: string

button()

Adds a Webfuse button to the current page. When a user clicks the Webfuse Button, it will create a new Session and will render this in a maximized iFrame on the current page, effectively starting the Session.

space.button(buttonSettings?: {
    position?: "topleft" | "topright" | "bottomleft" | "bottomright";
}): object

Parameters

buttonSettings

Settings that will be applied to the button and Sessions created with it.

Returns

A webfuse button object.

Example

space.button({
    position: 'bottomleft'
});

session()

space.session(options?:object, link?: string, sessionId?: string): object

Creates a Session object with the provided settings. You can bind callbacks using .on() method to hook on specific events fired during the Session lifetime.

Parameters

options

Session settings object. link
URL string with leader or follower Session Link. sessionId
Existing Session ID to restore.

Returns

A Eebfuse Session object.

Example

// Create a new Session
const session = space.session({block_until_agent_joins: true});

// Start the Session
const response = await session.start();
console.log('Session started:', response);

Session Object

The session object is returned by space.session() and represents a single Session.

const space = await webfuse
    .initSpace('**your widget key here**', '**your space id here**');
const session = space.session();

start()

Starts the Session. If a selector is provided, the Session will be embedded in the element matching that selector.

session.start(selector?: string): Promise<void>

Parameters

selector

CSS selector for the element to embed the Session in.

Returns

A promise that resolves with the Session object when the Session is started.

Example

const response = await session.start();

Use the Session API

You can use all the Session methods available on the Session object.

// Get the recently created Session
const session = webfuse.listSessions()[0];

// Open new tabs
session.openTab('https://www.example.com');
session.openTab('https://www.another-example.com');

// Get all open tabs
const tabs = session.getTabs();
console.log('Open tabs:', tabs);

Listen for Session Events

You can listen to various Session Events using the on method. This allows you to respond to different events that occur during a Session:

// Initialize Webfuse space and create a Session with event listeners
const space = await webfuse.initSpace('<WIDGET_KEY>', '<SPACE_ID>');
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();

Widget API

Widget Button

Widget API

Widget Snippet

isInsideSession

Example

currentSession

Example

initSpace()

Parameters

Returns

Example

listSessions()

Returns

Example

on()

Parameters

Returns

Example

Space Object

id

slug

button()

Parameters

Returns

Example

session()

Parameters

Returns

Example

Session Object

start()

Parameters

Returns

Example

Use the Session API

Listen for Session Events