Extension Structure

The source of an Extension comprises a directory that follows the following structure:

• DirectoryExtensionDirectory

  • manifest.json Contains Extension meta data.
  • content.js Injected into every single web page’s content, i.e., window scope.
  • background.js A persistent service worker that runs in the background.
  • popup.html A persistent, toggleable modal that pop up on top of the current page.
  • newtab.html A page that is initially displayed in every new tab.
  • Directoryexample_directory Individual files (assets, modules, …)

    • example.jpg
    • …
  • …

Only the manifest.json file is required. For instance: if you only want to customize the page that opens in a new tab, provide a newtab.html. Again, Webfuse Extensions aim for parity with browser Extensions. You can hence draw from knowledge, or adjacent information regarding web/browser extensions.

Caution

While uploading an Extension, Webfuse recursively scans the entire Extension directory with the following rules and limitations:

• Maximum file size 10MB per file.
• Hidden files and directories (names starting with ’.’) are skipped.
• Files that do not resolve to one of the below MIME types are skipped:
  • Text text/* (e.g. text/plain, text/html, text/css, etc.), JavaScript (application/javascript, text/js), JSON (application/json)
  • Image image/* (e.g. image/png, image/jpeg, image/gif, image/webp, image/svg+xml, etc.)
  • Audio Any audio MIME types audio/* (e.g. audio/mpeg, audio/wav, audio/ogg, etc.)
  • Video Any video MIME types video/* (e.g. video/mp4, video/webm, video/ogg, etc.)
  • other PDF (application/pdf), XML (application/xml)

Manifest

The entry point of an Extension is the manifest.json file, which is a JSON file that contains meta information about the Extension, such as name, version, and relative paths to component files.

{
    "manifest_version": 3,

    "name": "example-extension",
    "version": "1.0",
    "background": {
        "service_worker": "background.js"
    },
    "content_scripts": [
        {
            "js": ["content.js"],
            "matches": ["<all_urls>"]
        }
    ],
    "action": {
        "default_popup": "popup.html"
    },
    "chrome_url_overrides": {
        "newtab": "newtab.html"
    },
    "host_permissions": ["<all_urls>"],
    "homepage_url": "https://github.com/owner/repo",
    "virtualized_browser_only": true,
    "env": [
        {
            "key": "foo",
            "value": "bar",
            "description": "This is a description of the environment variable"
        }
    ]
}

Caution

Webfuse currently only supports web manifest version 3.

background.service_worker

The service worker which runs in a separate thread. It is available for all Session participants.

content_script

List of content scripts which will be loaded in all tabs. It is loaded only on the tab’s owner side:

• js (array): Array of JavaScript files to inject
• all_frames (boolean, optional): If true, script runs in all frames including iframes. If false (default), runs only in the main frame. This affects browser.tabs.sendMessage() frame targeting with the frameId option.

action.default_popup

This is the popup window which will be opened when the user clicks on a button in the Extension. It is available for all Session participants and will show the popup window with the content of the specified HTML file.

Caution

The popup component is not loaded when the UI is hidden (hide_session_ui: true), as it could not be toggled.

chrome_url_overrides.newtab

The new tab page which will be opened when the user clicks on the ’+’ button in the tab bar. It is available for all Session participants.

Note

The content script is not loaded in the custom new tab page.

host_permissions

List of URL patterns that will be accessible to the Extensions (e.g. sending a request to a specific URL from popup or background script).

A match pattern is a URL with the following structure, used to specify a group of URLs:

<scheme>://<host>/<path>

• scheme: Must be one of the following, separated from the rest of the pattern using a colon followed by a double slash (://): http, https, wildcard *, which matches both http and https.

• host: A hostname (www.example.com). A * before the hostname to match subdomains (*.example.com), or just a wildcard *. - If you use a wildcard in the host pattern, it must be the first or only character, and it must be followed by a period (.) or forward slash (/).

• path: A URL path (/example). For host permissions, the path is required but ignored. The wildcard (/*) should be used by convention.

Special case:

"<all_urls>" - Matches any URL that starts with a permitted scheme

Read more about match patterns here.

homepage_url

The URL of the homepage of the Extension. If defined and is a valid public GitHub repository URL, the Extension can be imported from a template.

virtualized_browser_only Webfuse Exclusive

• If the virtualized_browser_only flag is set to true, the Extension will be loaded only in the virtualized browser. This is useful if you want to offload some operations to the virtualized browser. You can also use this feature to hide some functionality or data from the end-user (e.g. credentials, etc.).

Caution

This feature requires the automation permission and Virtual Participant app to be installed in the space.

You can also use this feature to create a virtual participant and control your Session using the Automation API

env Webfuse Exclusive

You can use the env key to pass environment variables to the Extension. These variables will be available in all components of the Extension. To use environment variables defined in the manifest.json file, you can use the browser.webfuseSession.env object. This is useful if you want to use some shared data between components of the Extension or if you want to make your Extensions shareable and let users pass their own values to the Extension. If you want to share your Extension with environment variables feature to someone else, you can share a manifest.json file with env section populated with the objects with values as empty strings:

{
    "env": [
        {
            "key": "foo",
            "value": "",
            "description": "This is a description of the environment variable"
        }
    ]
}

Browser Console

console.log(browser.webfuseSession.env.foo); // bar

After that, variables can be set or overridden from the Session Editor’s Extension details tab.

Background Component

The service worker is a script that can handle all logic of the Extension - it is run on every participant’s side as soon as they join the Session.

Content Component

The content script is a script that is injected into each web page. This is a script that is executed in the context of the web page and only on the Tab Owner’s side. This script has access to the DOM of the web page and can manipulate it.

You can have multiple instances of this script running - one for each tab and or each iFrames.

Tip

When you have not customized the DOMAIN NAME of the Space or are on the FREE plan than whenever your Extension loads a content script it will require permission from the user to load the script.

Popup Component

The popup page is a window that is opened when the user clicks on a button in the Extension, its content is defined by the HTML file specified in the manifest.json file.

Caution

For persistent state, it is recommended to use the Background Component, as the lifetime of the Popup is not guaranteed across open and closed states.

Newtab Component

The new tab page is a page that is opened when the user clicks on the ’+’ button to open a new tab - or when the Session is started to specifically open the New Tab Page. By configuring this page you can basically customize the new tab page within Sessions allowing you to style it as you want. By default, Webfuse shows a URL input field, and possibly buttons for collaborative features.