Merge pull request #13027 from vector-im/travis/jitsi-docs

Add some docs about Jitsi widgets and Jitsi configuration
This commit is contained in:
Travis Ralston 2020-04-06 15:03:17 -06:00 committed by GitHub
commit cb39edbfd7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 143 additions and 1 deletions

View file

@ -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.

94
docs/jitsi-dev.md Normal file
View file

@ -0,0 +1,94 @@
# 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 <url>` 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. The widgets themselves *should* also work outside of
Riot. Widgets currently have a "pop out" button which opens them in a new tab and
therefore have no connection back to Riot.
## 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. If there's only two
people in the room, a plain WebRTC call is made instead of using a widget at all - these
are defined in the Matrix specification.
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.

47
docs/jitsi.md Normal file
View file

@ -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 directly between clients or via TURN servers configured on the 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.
## 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. This is a known bug and which needs to be fixed.