Plugin Versioning

Welcome to the BigBlueButton html plugin SDK.

This repository has the code of the SDK used to develop a plugin.

Mind that we have a different branch for each version of the SDK. This happens so we garantee that everything merged on one of the branches is compatible with the CORE in its correspondent version. As for now, see a correspondence of branches, SDK versions and BBB core version.

Repository Branch	Plugin-SDK Version	BigBlueButton Core Version
v0.0.x	v0.0.x	v3.0.x
v0.1.x	v0.1.x	v3.1.x

See that this branch (main) does not contain any code, that's because this branch is used only for basic documentation. If you want further information about the pluginApi features themselves, see the documentation (readme files) within the specific branch you are interested in. We do this separation because from now on, v0.1.x is becoming more and more different from the other one v0.0.x.

If you have any suggestions, requirements or questions, don't hesitate to contat us.

With that said, here it follows the basic documentation of the pluginSdk:

BigBlueButton SDK for HTML5 Client Plugins

This repository contains the SDK for developing BigBlueButton plugins. Plugins are React components that can be loaded from external sources by the BigBlueButton HTML5 client to extend its functionalities.

Overview

An overview of the plugin architecture and capabilities can be found here.

Usage

This is a general instruction on how to use a plugin. For a detailed configuration example of each use case, have a look at the READMEs in the respective samples-folders.

Running the Plugin from Source

For development purposes you can run a plugin locally from source.

For example if you take the sample-action-button-dropdown-plugin, you do the following:

Running from source code with local BBB-server

1. Start the development server:

   cd $HOME/src/bigbluebutton-html-plugin-sdk/samples/sample-action-button-dropdown-plugin
   npm install
   npm start

2. Add reference to it on BigBlueButton's /create call or add it on /usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties:

pluginManifests=[{"url": "http://localhost:4701/manifest.json"}]

Running from souce code with a remote BBB-server

If you are running your BBB-server elsewhere, than you can't simply point the manifest URL to a local address, you'll need to either serve the built version into a CDN or serve the dev version using a service to make it public. And for the second option we'd recommend NGROK. Here are the instructions to do that:

1. Create an account on https://ngrok.com/ (Official website of NGROK);

2. Install NGROK in your computer. They have a guide for that right after you created your account;

3. Start the Plugin development server:

cd $HOME/src/plugin-pick-random-user-plugin
npm install
npm start

4. Start the NGROK server into your machine with the following command:

ngrok http http://172.17.0.1:4701

Make sure to point NGROK to the correct local URL (In our case - The samples are made this way, for instance - we used http://172.17.0.1:4701)

Right after that, NGROK will create an interface into your terminal and will display the URL which your static files are being served.

Here's an example of URL: https://<uuid>.ngrok-free.app

You can already interact with this URL and access both

https://<uuid>.ngrok-free.app/manifest.json

or

https://<uuid>.ngrok-free.app/PickRandomUserPlugin.js

5. Add this create parameter into the API-mate of the server you are testing it on:

pluginManifests=[{"url": "https://<uuid>.ngrok-free.app/manifest.json"}]

And there you go, you can test it freely.

Building the Plugin (Production)

To build a plugin for production use (again, using the example of sample-action-button-dropdown-plugin), follow these steps:

cd $HOME/src/bigbluebutton-html-plugin-sdk/samples/sample-action-button-dropdown-plugin
npm ci
npm run build-bundle

The above command will generate the dist folder, containing the bundled JavaScript file named SampleActionButtonDropdownPlugin.js along with the manifest.json. These files can be hosted on any HTTPS server.

To use the plugin with BigBlueButton, add the plugin's manifest.json URL to bigbluebutton.properties or you can simply send it via /create parameter:

pluginManifests=[{"url":"<your-domain>/path/to/manifest.json"}]

Hosting the Plugin on a BBB Server

While the plugin can be hosted on any Server, it is also possible to host the bundled file directly on a BigBlueButton server. For that you copy dist/SampleActionButtonDropdownPlugin.js and dist/manifest.json to the folder /var/www/bigbluebutton-default/assets/plugins/sampleActionButtonDropdownPlugin. In this case, the your manifest URL will be https://<your-host>/plugins/sampleActionButtonDropdownPlugin/manifest.json.

Manifest Json

Here is as complete manifet.json example with all possible configurations:

{
  "requiredSdkVersion": "<version>",
  "name": "MyPlugin",
  "javascriptEntrypointUrl": "MyPlugin.js",
  "localesBaseUrl": "https://cdn.domain.com/my-plugin/", // Optional
  "dataChannels":[
    {
      "name": "public-channel",
      "pushPermission": ["moderator","presenter"], // "moderator","presenter", "all"
      "replaceOrDeletePermission": ["moderator", "creator"] // "moderator", "presenter","all", "creator"
    }
  ], // One can enable more data-channels to better organize client communication
  "eventPersistence": {
    "isEnabled": true, // By default it is not enabled
    "maximumPayloadSizeInBytes": 1024,
    "rateLimiting": {
      "messagesAllowedPerSecond": 10,
      "messagesAllowedPerMinute": 20
    }
  },
  "remoteDataSources": [
    {
      "name": "allUsers",
      "url": "${meta_pluginSettingsUserInformation}",
      "fetchMode": "onMeetingCreate", // Possible values: "onMeetingCreate", "onDemand" 
      "permissions": ["moderator", "viewer"]
    }
  ]
}