From abf475ee80f3600dde5cd14afb07adfd3a9983d0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 3 Apr 2020 13:25:33 -0600 Subject: [PATCH] Add some docs about Jitsi widgets and Jitsi configuration --- docs/config.md | 3 +- docs/jitsi-dev.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++ docs/jitsi.md | 47 +++++++++++++++++++++++++ 3 files changed, 139 insertions(+), 1 deletion(-) create mode 100644 docs/jitsi-dev.md create mode 100644 docs/jitsi.md diff --git a/docs/config.md b/docs/config.md index 1471faf9a4..3102eaf83e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -84,7 +84,8 @@ For a good example, see https://riot.im/develop/config.json. By default, this is "https://matrix.to" to generate matrix.to (spec) permalinks. Set this to your Riot instance URL if you run an unfederated server (eg: "https://riot.example.org"). -1. `jitsi`: Used to change the default conference options. +1. `jitsi`: Used to change the default conference options. Learn more about the + Jitsi options at [jitsi.md](./jitsi.md). 1. `preferredDomain`: The domain name of the preferred Jitsi instance. Defaults to `jitsi.riot.im`. This is used whenever a user clicks on the voice/video call buttons - integration managers may use a different domain. diff --git a/docs/jitsi-dev.md b/docs/jitsi-dev.md new file mode 100644 index 0000000000..24ec776ff0 --- /dev/null +++ b/docs/jitsi-dev.md @@ -0,0 +1,90 @@ +# Jitsi wrapper developer docs + +*If you're looking for information on how to set up Jitsi in your Riot, see +[jitsi.md](./jitsi.md) instead.* + +These docs are for developers wondering how the different conference buttons work +within Riot. If you're not a developer, you're probably looking for [jitsi.md](./jitsi.md). + +## Brief introduction to widgets + +Widgets are embedded web applications in a room, controlled through state events, and +have a `url` property. They are largely specified by [MSC1236](https://github.com/matrix-org/matrix-doc/issues/1236) +and have extensions proposed under [MSC1286](https://github.com/matrix-org/matrix-doc/issues/1286). + +The `url` is typically something we shove into an iframe with sandboxing (see `AppTile` +in the react-sdk), though for some widgets special integration can be done. v2 widgets +have a `data` object which helps achieve that special integration, though v1 widgets +are best iframed and left alone. + +Widgets have a `postMessage` API they can use to interact with Riot, which also allows +Riot to interact with them. Typically this is most used by the sticker picker (an +account-level widget), though widgets like the Jitsi widget will request permissions to +get 'stuck' into the room list during a conference. + +Widgets can be added with the `/addwidget ` command. + +## Brief introduction to integration managers + +Integration managers (like Scalar and Dimension) are accessible via the 4 squares in +the top right of the room and provide a simple UI over top of bridges, bots, and other +stuff to plug into a room. They are a separate service to Riot and are thus iframed +in a dialog as well. They also have a `postMessage` API they can use to interact with +the client to create things like widgets, give permissions to bridges, and generally +set everything up for the integration the user is working with. + +Integration managers do not currently have a spec associated with them, though efforts +are underway in [MSC1286](https://github.com/matrix-org/matrix-doc/issues/1286). + +## Widgets configured by integration managers + +Integration managers will often "wrap" a widget by using a widget `url` which points +to the integration manager instead of to where the user requested the widget be. For +example, a custom widget added in an integration manager for https://matrix.org will +end up creating a widget with a URL like `https://integrations.example.org?widgetUrl=https%3A%2F%2Fmatrix.org`. + +The integration manager's wrapper will typically have another iframe to isolate the +widget from the client by yet another layer. The wrapper often provides other functionality +which might not be available on the embedded site, such as a fullscreen button or the +communication layer with the client (all widgets *should* be talking to the client +over `postMessage`, even if they aren't going to be using the widget APIs). + +Widgets added with the `/addwidget` command will *not* be wrapped as they are not going +through an integration manager. + +## Jitsi widgets from integration managers + +Integration managers will create an entire widget event and send it over `postMessage` +for the client to add to the room. This means that the integration manager gets to +decide the conference domain, conference name, and other aspects of the widget. As +a result, users can end up with a Jitsi widget that does not use the same conference +server they specified in their config.json - this is expected. + +Some integration managers allow the user to change the conference name while others +will generate one for the user. + +## Jitsi widgets generated by Riot itself + +When the user clicks on the call buttons by the composer, the integration manager is +not involved in the slightest. Instead, Riot itself generates a widget event, this time +using the config.json parameters, and publishes that to the room. + +The Jitsi widget created by Riot uses a local `jitsi.html` wrapper (or one hosted by +`https://riot.im/app` for desktop users or those on non-https domains) as the widget +`url`. The wrapper has some basic functionality for talking to Riot to ensure the +required `postMessage` calls are fulfilled. + +## The Jitsi wrapper in Riot + +Whenever Riot sees a Jitsi widget, it ditches the `url` and instead replaces it with +its local wrapper, much like what it would do when creating a widget. However, instead +of using one from riot.im/app, it will use one local to the client instead. + +The wrapper is used to provide a consistent experience to users, as well as being faster +and less risky to load. The local wrapper URL is populated with the conference information +from the original widget (which could be a v1 or v2 widget) so the user joins the right +call. + +Critically, when the widget URL is reconstructed it does *not* take into account the +config.json's `preferredDomain` for Jitsi. If it did this, users would end up on different +conference servers and therefore different calls entirely. diff --git a/docs/jitsi.md b/docs/jitsi.md new file mode 100644 index 0000000000..43708ee373 --- /dev/null +++ b/docs/jitsi.md @@ -0,0 +1,47 @@ +# Jitsi in Riot + +Riot uses [Jitsi](https://jitsi.org/) for conference calls, which provides options for +self-hosting your own server and supports most major platforms. + +1:1 calls, or calls between you and one other person, do not use Jitsi. Instead, those +calls work through a TURN server configured on your respective homeservers. + +There's a number of ways to start a Jitsi call: the easiest way is to click on the +voice or video buttons near the message composer in a room with more than 2 people. This +will add a Jitsi widget which allows anyone in the room to join. + +Integration managers (available through the 4 squares in the top right of the room) may +provide their own approaches for adding Jitsi widgets, though these are now considered +legacy and should only be used in specific circumstances. + +## Configuring Riot to use your self-hosted Jitsi server + +Riot will use the Jitsi server that is embedded in the widget, even if it is not the +one you configured. This is because conference calls must be held on a single Jitsi +server and cannot be split over multiple servers. + +However, you can configure Riot to *start* a conference with your Jitsi server by adding +to your [config](./config.md) the following: +```json +{ + "jitsi": { + "preferredDomain": "your.jitsi.example.org" + } +} +``` + +The default is `jitsi.riot.im` (a free service offered by Riot), and the demo site for +Jitsi uses `meet.jit.si` (also free). + +Once you've applied the config change, refresh Riot and press the call button. This +should start a new conference on your Jitsi server. + +**Note**: The widget URL will point to a `jitsi.html` page hosted by Riot. The Jitsi +domain will appear later in the URL as a configuration parameter. + +## Mobile app support + +Currently the Riot mobile apps do not support custom Jitsi servers and will instead +use the default `jitsi.riot.im` server. When users on the mobile apps join the call, +they will be joining a different conference which has the same name, but not the same +participants.