Matrix/element-call-Github
1
0
Fork 0
mirror of https://github.com/vector-im/element-call.git synced 2024-11-30 00:50:48 +08:00
Code Issues Packages Projects Releases Wiki Activity
e12f4fada0
element-call-Github/docs/url-params.md

63 lines
17 KiB
Markdown
Raw Normal View History

Allow Element Call theme configuration via url. (#2203) Signed-off-by: Timo K <toger5@hotmail.de> Co-authored-by: Robin <robin@robin.town>
2024-02-22 23:15:46 +08:00
# Url Format and parameters
Document url properties (#1731) * document url properties --------- Signed-off-by: Timo K <toger5@hotmail.de>
2023-10-26 17:18:12 +08:00
There are two formats for Element Call urls.
- **Current Format**
Allow Element Call theme configuration via url. (#2203) Signed-off-by: Timo K <toger5@hotmail.de> Co-authored-by: Robin <robin@robin.town>
2024-02-22 23:15:46 +08:00
```text
Document url properties (#1731) * document url properties --------- Signed-off-by: Timo K <toger5@hotmail.de>
2023-10-26 17:18:12 +08:00
https://element_call.domain/room/#
/<room_name_alias>?roomId=!id:domain&password=1234&<other params see below>
```
Allow Element Call theme configuration via url. (#2203) Signed-off-by: Timo K <toger5@hotmail.de> Co-authored-by: Robin <robin@robin.town>
2024-02-22 23:15:46 +08:00
The url is split into two sections. The `https://element_call.domain/room/#`
contains the app and the intend that the link brings you into a specific room
(`https://call.element.io/#` would be the homepage). The fragment is used for
query parameters to make sure they never get sent to the element_call.domain
server. Here we have the actual matrix roomId and the password which are used
to connect all participants with e2ee. This allows that `<room_name_alias>` does
not need to be unique. Multiple meetings with the label weekly-sync can be created
without collisions.
Document url properties (#1731) * document url properties --------- Signed-off-by: Timo K <toger5@hotmail.de>
2023-10-26 17:18:12 +08:00
- **deprecated**
Allow Element Call theme configuration via url. (#2203) Signed-off-by: Timo K <toger5@hotmail.de> Co-authored-by: Robin <robin@robin.town>
2024-02-22 23:15:46 +08:00
```text
Document url properties (#1731) * document url properties --------- Signed-off-by: Timo K <toger5@hotmail.de>
2023-10-26 17:18:12 +08:00
https://element_call.domain/<room_name>
```
Allow Element Call theme configuration via url. (#2203) Signed-off-by: Timo K <toger5@hotmail.de> Co-authored-by: Robin <robin@robin.town>
2024-02-22 23:15:46 +08:00
With this format the livekit alias that will be used is the `<room_name>`.
Refactor URL parameters into table (#2827) * Refactor URL parameters into table This is for readability and ahead of some possible changes * Whitespace * Lint * Cleanup and correct fontScale
2024-11-23 16:51:27 +08:00
All people connecting to this URL will end up in the same unencrypted room.
Allow Element Call theme configuration via url. (#2203) Signed-off-by: Timo K <toger5@hotmail.de> Co-authored-by: Robin <robin@robin.town>
2024-02-22 23:15:46 +08:00
This does not scale, is super unsecure
Refactor URL parameters into table (#2827) * Refactor URL parameters into table This is for readability and ahead of some possible changes * Whitespace * Lint * Cleanup and correct fontScale
2024-11-23 16:51:27 +08:00
(people could end up in the same room by accident) and it also is not really
Allow Element Call theme configuration via url. (#2203) Signed-off-by: Timo K <toger5@hotmail.de> Co-authored-by: Robin <robin@robin.town>
2024-02-22 23:15:46 +08:00
possible to support encryption.
Document url properties (#1731) * document url properties --------- Signed-off-by: Timo K <toger5@hotmail.de>
2023-10-26 17:18:12 +08:00
Refactor URL parameters into table (#2827) * Refactor URL parameters into table This is for readability and ahead of some possible changes * Whitespace * Lint * Cleanup and correct fontScale
2024-11-23 16:51:27 +08:00
## Parameters
| Name | Values | Required for widget | Required for SPA | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowIceFallback` | `true` or `false` | No, defaults to `false` | No, defaults to `false` | Allows use of fallback STUN servers for ICE if the user's homeserver doesn’t provide any. |
| `analyticsID` | Posthog analytics ID | No | No | Available only with user's consent for sharing telemetry in Element Web. |
| `appPrompt` | `true` or `false` | No, defaults to `true` | No, defaults to `true` | Prompts the user to launch the native mobile app upon entering a room, applicable only on Android and iOS, and must be enabled in config. |
| `baseUrl` | | Yes | Not applicable | The base URL of the homeserver to use for media lookups. |
| `confineToRoom` | `true` or `false` | No, defaults to `false` | No, defaults to `false` | Keeps the user confined to the current call/room. |
| `deviceId` | Matrix device ID | Yes | Not applicable | The Matrix device ID for the widget host. |
| `displayName` | | No | No | Display name used for auto-registration. |
| `enableE2EE` (deprecated) | `true` or `false` | No, defaults to `true` | No, defaults to `true` | Legacy flag to enable end-to-end encryption, not used in the `livekit` branch. |
Mute state improvements including muting if skipLobby=true in SPA (Based on #2834) (#2846)
2024-11-29 01:05:12 +08:00
| `fontScale` | A decimal number such as `0.9` | No, defaults to `1.0` | No, defaults to `1.0` | Factor by which to scale the interface's font size. |
Refactor URL parameters into table (#2827) * Refactor URL parameters into table This is for readability and ahead of some possible changes * Whitespace * Lint * Cleanup and correct fontScale
2024-11-23 16:51:27 +08:00
| `fonts` | | No | No | Defines the font(s) used by the interface. Multiple font parameters can be specified: `?font=font-one&font=font-two...`. |
| `hideHeader` | `true` or `false` | No, defaults to `false` | No, defaults to `false` | Hides the room header when in a call. |
| `hideScreensharing` | `true` or `false` | No, defaults to `false` | No, defaults to `false` | Hides the screen-sharing button. |
| `homeserver` | | Not applicable | No | Homeserver for registering a new (guest) user, configures non-default guest user server when creating a spa link. |
| `lang` | [BCP 47](https://www.rfc-editor.org/info/bcp47) code | No | No | The language the app should use. |
| `parentUrl` | | Yes | Not applicable | The url used to send widget action postMessages. This should be the domain of the client or the webview the widget is hosted in. (in case the widget is not in an Iframe but in a dedicated webview we send the postMessages same WebView the widget lives in. Filtering is done in the widget so it ignores the messages it receives from itself) |
| `password` | | No | No | E2EE password when using a shared secret. (For individual sender keys in embedded mode this is not required.) |
| `perParticipantE2EE` | `true` or `false` | No, defaults to `false` | No, defaults to `false` | Enables per participant encryption with Keys exchanged over encrypted matrix room messages. |
| `preload` | `true` or `false` | No, defaults to `false` | Not applicable | Pauses app before joining a call until an `io.element.join` widget action is seen, allowing preloading. |
| `returnToLobby` | `true` or `false` | No, defaults to `false` | Not applicable | Displays the lobby in widget mode after leaving a call; shows a blank page if set to `false`. Useful for video rooms. |
| `roomId` | [Matrix Room ID](https://spec.matrix.org/v1.12/appendices/#room-ids) | Yes | No | Anything about what room we're pointed to should be from useRoomIdentifier which parses the path and resolves alias with respect to the default server name, however roomId is an exception as we need the room ID in embedded widget mode, and not the room alias (or even the via params because we are not trying to join it). This is also not validated, where it is in `useRoomIdentifier()`. |
| `showControls` | `true` or `false` | No, defaults to `true` | No, defaults to `true` | Displays controls like mute, screen-share, invite, and hangup buttons during a call. |
Mute state improvements including muting if skipLobby=true in SPA (Based on #2834) (#2846)
2024-11-29 01:05:12 +08:00
| `skipLobby` | `true` or `false` | No, defaults to `false` | No, defaults to `false` | Skips the lobby to join a call directly, can be combined with preload in widget. When `true` the audio and video inputs will be muted by default. (This means there currently is no way to start without muted video if one wants to skip the lobby. Also not in widget mode.) |
Refactor URL parameters into table (#2827) * Refactor URL parameters into table This is for readability and ahead of some possible changes * Whitespace * Lint * Cleanup and correct fontScale
2024-11-23 16:51:27 +08:00
| `theme` | One of: `light`, `dark`, `light-high-contrast`, `dark-high-contrast` | No, defaults to `dark` | No, defaults to `dark` | UI theme to use. |
| `userId` | [Matrix User Identifier](https://spec.matrix.org/v1.12/appendices/#user-identifiers) | Yes | Not applicable | The Matrix user ID. |
| `viaServers` | Comma separated list of [Matrix Server Names](https://spec.matrix.org/v1.12/appendices/#server-name) | Not applicable | No | Homeserver for joining a room, non-empty value required for rooms not on the user’s default homeserver. |
| `widgetId` | [MSC2774](https://github.com/matrix-org/matrix-spec-proposals/pull/2774) format widget ID | Yes | Not applicable | The id used by the widget. The presence of this parameter implies that element call will not connect to a homeserver directly and instead tries to establish postMessage communication via the `parentUrl`. |
Reference in New Issue Copy Permalink