mirror of
https://github.com/vector-im/element-web.git
synced 2024-09-09 22:55:12 +00:00
Merge pull request #13027 from vector-im/travis/jitsi-docs
Add some docs about Jitsi widgets and Jitsi configuration
This commit is contained in:
commit
cb39edbfd7
3 changed files with 143 additions and 1 deletions
|
@ -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
94
docs/jitsi-dev.md
Normal 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
47
docs/jitsi.md
Normal 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.
|
Loading…
Reference in a new issue