mad-star-studio/element-web
2
0
Fork 0
Code Pull requests Activity

Update SdkConfig usage to use new translation layer + update config.md docs (#21429)

Browse source 
* Update SdkConfig usage to use new translation layer

* Appease the linter

* WIP refactor of config documentation

* Finish re-writing config.md

* Update surrounding documentation

* Apply suggestions from code review

Co-authored-by: Germain <germains@element.io>

* Textual updates

Co-authored-by: Germain <germains@element.io>
This commit is contained in:
Travis Ralston 2022-03-18 10:12:44 -06:00 • committed by GitHub
parent 071a5410b8
commit 1384783a77
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 526 additions and 249 deletions
Download patch file Download diff file Expand all files Collapse all files

680
docs/config.md
View file

@ -1,211 +1,467 @@
Configuration
=============
# Configuration
You can configure the app by copying `config.sample.json` to
`config.json` and customising it:
You can configure the app by copying `config.sample.json` to `config.json` and customising it. The possible options are
described here. If you run into issues, please visit [#element-web:matrix.org](https://matrix.to/#/#element-web:matrix.org)
on Matrix.
For a good example, see https://develop.element.io/config.json.
For a good example of a production-tuned config, see https://app.element.io/config.json
1. `default_server_config` sets the default homeserver and identity server URL for
Element to use. The object is the same as returned by [https://<server_name>/.well-known/matrix/client](https://matrix.org/docs/spec/client_server/latest.html#get-well-known-matrix-client),
with added support for a `server_name` under the `m.homeserver` section to display
a custom homeserver name. Alternatively, the config can contain a `default_server_name`
instead which is where Element will go to get that same object, although this option is
deprecated - see the `.well-known` link above for more information on using this option.
Note that the `default_server_name` is used to get a complete server configuration
whereas the `server_name` in the `default_server_config` is for display purposes only.
* *Note*: The URLs can also be individually specified as `default_hs_url` and
`default_is_url`, however these are deprecated. They are maintained for backwards
compatibility with older configurations. `default_is_url` is respected only
if `default_hs_url` is used.
* Element will fail to load if a mix of `default_server_config`, `default_server_name`, or
`default_hs_url` is specified. When multiple sources are specified, it is unclear
which should take priority and therefore the application cannot continue.
* As of Element 1.4.0, identity servers are optional. See [Identity servers](#identity-servers) below.
1. `sso_redirect_options`: Optionally defines how Element will behave with a server which supports
Single Sign On (SSO). By default, Element will do nothing special and simply show a button where
needed for the user to click to navigate to the SSO system. This behaviour can be tuned with the
config options below (as properties of the `sso_redirect_options` object). None of the options apply
if Element thinks the user is already logged in, and similarly Element will assume the default server
supports SSO if these redirect options are used.
* `immediate`: When `true` (default `false`), Element will automatically redirect all unauthenticated
users to the SSO system to log in regardless of how they reached the app. This overrides the use of
other redirect options.
* `on_welcome_page`: When `true` (default `false`), Element will automatically redirect all unauthenticated
users to the SSO to log in if the user lands on the welcome page or no specific page. For example,
https://app.element.io/#/welcome and https://app.element.io would redirect if set up to use this option.
This can be useful to maintain guest experience until an account is needed.
1. `logout_redirect_url`: After Element has cleared the user's storage, the user will be redirected to this URL.
Typically most useful in environments where the account users will be logging into is managed for them, such
as in cases of some SSO deployments. For example: this page might log the user out of the SSO system too.
1. `features`: Lookup of optional features that may be force-enabled (`true`) or force-disabled (`false`).
When features are not listed here, their defaults will be used, and users can turn them on/off if `showLabsSettings`
allows them to. The available optional experimental features vary from release to release and are
[documented](labs.md). The feature flag process is [documented](feature-flags.md) as well.
1. `showLabsSettings`: Shows the "labs" tab of user settings. Useful to allow users to turn on experimental features
they might not otherwise have access to.
1. `brand`: String to pass to your homeserver when configuring email notifications, to let the
homeserver know what email template to use when talking to you.
1. `branding`: Configures various branding and logo details, such as:
1. `welcomeBackgroundUrl`: An image to use as a wallpaper outside the app
during authentication flows. If an array is passed, an image is chosen randomly for each visit.
1. `authHeaderLogoUrl`: An logo image that is shown in the header during
authentication flows
1. `authFooterLinks`: a list of links to show in the authentication page footer:
`[{"text": "Link text", "url": "https://link.target"}, {"text": "Other link", ...}]`
1. `reportEvent`: Configures the dialog for reporting content to the homeserver
admin.
1. `adminMessageMD`: An extra message to show on the reporting dialog to
mention homeserver-specific policies. Accepts Markdown.
1. `integrations_ui_url`: URL to the web interface for the integrations server. The integrations
server is not Element and normally not your homeserver either. The integration server settings
may be left blank to disable integrations.
1. `integrations_rest_url`: URL to the REST interface for the integrations server.
1. `integrations_widgets_urls`: list of URLs to the REST interface for the widget integrations server.
1. `bug_report_endpoint_url`: endpoint to send bug reports to (must be running a
https://github.com/matrix-org/rageshake server). Bug reports are sent when a user clicks
"Send Logs" within the application. Bug reports can be disabled/hidden by leaving the
`bug_report_endpoint_url` out of your config file.
1. `uisi_autorageshake_app`: If users enable the Labs flag
"Automatically send debug logs on decryption errors", rageshakes
submitted by that feature can be given a custom app name so that
the rageshake server can file them in a separate issue tracker. If
this field is absent from the config, the app name for decryption
error rageshakes will be `"element-web"` just like for
manually-submitted rageshakes.
For an example of a development/beta-tuned config, see https://develop.element.io/config.json
If `bug_report_endpoint_url` is set to Element's rageshake server,
then this field should be set to `"element-auto-uisi"` as in
`config.sample.json`. If `bug_report_endpoint_url` is left out,
this field has no effect and can be left out as well. If you are
using your own rageshake server, set this field in accordance with
your rageshake server configuration.
1. `roomDirectory`: config for the public room directory. This section is optional.
1. `roomDirectory.servers`: List of other homeservers' directories to include in the drop
down list. Optional.
1. `default_theme`: name of theme to use by default (e.g. 'light')
1. `update_base_url` (electron app only): HTTPS URL to a web server to download
updates from. This should be the path to the directory containing `macos`
and `win32` (for update packages, not installer packages).
1. DEPRECATED: `piwik`: Analytics can be disabled by setting `piwik: false` or by leaving the piwik config
option out of your config file. If you want to enable analytics, set `piwik` to be an object
containing the following properties:
1. `url`: The URL of the Piwik instance to use for collecting analytics
1. `whitelistedHSUrls`: a list of HS URLs to not redact from the analytics
1. `whitelistedISUrls`: a list of IS URLs to not redact from the analytics
1. `siteId`: The Piwik Site ID to use when sending analytics to the Piwik server configured above
1. `welcomeUserId`: the user ID of a bot to invite whenever users register that can give them a tour
1. `embeddedPages`: Configures the pages displayed in portions of Element that
embed static files, such as:
1. `welcomeUrl`: Initial content shown on the outside of the app when not
logged in. Defaults to `welcome.html` supplied with Element.
1. `homeUrl`: Content shown on the inside of the app when a specific room is
not selected. By default, no home page is configured. If one is set, a
button to access it will be shown in the top left menu.
1. `loginForWelcome`: Overrides `welcomeUrl` to make the welcome page be the
same page as the login page when `true`. This effectively disables the
welcome page.
1. `defaultCountryCode`: The ISO 3166 alpha2 country code to use when showing
country selectors, like the phone number input on the registration page.
Defaults to `GB` if the given code is unknown or not provided.
1. `settingDefaults`: Defaults for settings that support the `config` level,
as an object mapping setting name to value (note that the "theme" setting
is special cased to the `default_theme` in the config file).
1. `disable_custom_urls`: disallow the user to change the
default homeserver when signing up or logging in.
1. `permalinkPrefix`: Used to change the URL that Element generates permalinks with.
By default, this is "https://matrix.to" to generate matrix.to (spec) permalinks.
Set this to your Element instance URL if you run an unfederated server (eg:
"https://element.example.org").
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 `meet.element.io`. This is used whenever a user clicks on the voice/video
call buttons - integration managers may use a different domain.
This setting is ignored if your homeserver provides
`/.well-known/matrix/client` in its well-known location, and the JSON file
at that location has a key `m.vector.riot.jitsi`. In this case, the
configuration found in the well-known location is used instead.
1. `jitsiWidget`: Options to change the built-in Jitsi widget behaviour. `jitsi` controls
how the widget gets created, but not how it behaves.
1. `skipBuiltInWelcomeScreen`: If you'd like to skip the default "Join Conference"
behaviour, set this to `true`. This will cause the widget to assume that there's
a Jitsi welcome screen set up and point the user towards that. Note that this can
cause the camera/microphone to flicker as "in use" while Jitsi tests the devices.
1. `enable_presence_by_hs_url`: The property key should be the URL of the homeserver
and its value defines whether to enable/disable the presence status display
from that homeserver. If no options are configured, presence is shown for all
homeservers.
1. `disable_guests`: Disables guest access tokens and auto-guest registrations.
Defaults to false (guests are allowed).
1. `disable_login_language_selector`: Disables the login language selector. Defaults
to false (language selector is shown).
1. `disable_3pid_login`: Disables 3rd party identity options on login and registration form
Defaults to false (3rd party identity options are shown).
1. `default_federate`: Default option for room federation when creating a room
Defaults to true (room federation enabled).
1. `desktopBuilds`: Used to alter promotional links to the desktop app. By default
the builds are considered available and accessible from https://element.io. This
config option is typically used in the context of encouraging encrypted message
search capabilities (Seshat). All the options listed below are required if this
option is specified.
1. `available`: When false, the desktop app will not be promoted to the user.
1. `logo`: An HTTP URL to the avatar for the desktop build. Should be 24x24, ideally
an SVG.
1. `url`: An HTTP URL for where to send the user to download the desktop build.
1. `mobileBuilds`: Used to alter promotional links to the mobile app. By default the
builds are considered available and accessible from https://element.io. This config
option is typically used in a context of encouraging the user to try the mobile app
instead of a mobile/incompatible browser.
1. `ios`: The URL to the iOS build. If `null`, it will be assumed to be not available.
If not set, the default element.io builds will be used.
1. `android`: The URL to the Android build. If `null`, it will be assumed to be not available.
If not set, the default element.io builds will be used.
1. `fdroid`: The URL to the FDroid build. If `null`, it will be assumed to be not available.
If not set, the default element.io builds will be used.
1. `mobileGuideToast`: Whether to show a toast a startup which nudges users on
iOS and Android towards the native mobile apps. The toast redirects to the
mobile guide if they accept. Defaults to false.
1. `audioStreamUrl`: If supplied, show an option on Jitsi widgets to stream
audio using Jitsi's live streaming feature. This option is experimental and
may be removed at any time without notice.
1. `voip`: Behaviour related to calls
1. `obeyAssertedIdentity`: If set, MSC3086 asserted identity messages sent
on VoIP calls will cause the call to appear in the room corresponding to the
asserted identity. This *must* only be set in trusted environments.
1. `posthog`: [Posthog](https://posthog.com/) integration config. If not set, Posthog analytics are disabled.
1. `projectApiKey`: The Posthog project API key
2. `apiHost`: The Posthog API host
1. `sentry`: [Sentry](https://sentry.io/) configuration for rageshake data being sent to sentry.
1. `dsn`: the Sentry [DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/)
2. `environment`: (optional) The [Environment](https://docs.sentry.io/product/sentry-basics/environments/) to pass to sentry
1. `map_style_url`: Map tile server style URL for location sharing. e.g.
'https://api.maptiler.com/maps/streets/style.json?key=YOUR_KEY_GOES_HERE'
This setting is ignored if your homeserver provides
`/.well-known/matrix/client` in its well-known location, and the JSON file
at that location has a key `m.tile_server` (or the unstable version
`org.matrix.msc3488.tile_server`). In this case, the configuration found in
the well-known location is used instead.
1. `analyticsOwner`: The entity that analytics data is being sent to. Used in copy
when explaining to the user where data is being sent. If not set, defaults to `brand`.
1. `defaultDeviceDisplayName`: The default device display name to use for new logins
and registrations. If not set then a calculated version will be used.
1. `custom_translations_url`: An optional URL to allow overriding of translatable strings.
The JSON file must be in a format of `{"affected string": {"languageCode": "new string"}}`.
See https://github.com/matrix-org/matrix-react-sdk/pull/7886 for details.
After changing the config, the app will need to be reloaded. For web browsers this is a simple page refresh, however
for the desktop app the application will need to be exited fully (including via the task tray) and re-started.
Note that `index.html` also has an og:image meta tag that is set to an image
hosted on riot.im. This is the image used if links to your copy of Element
appear in some websites like Facebook, and indeed Element itself. This has to be
static in the HTML and an absolute URL (and HTTP rather than HTTPS), so it's
not possible for this to be an option in config.json. If you'd like to change
it, you can build Element, but run
`RIOT_OG_IMAGE_URL="http://example.com/logo.png" yarn build`.
Alternatively, you can edit the `og:image` meta tag in `index.html` directly
each time you download a new version of Element.
## Homeserver configuration
Identity servers
================
In order for Element to even start you will need to tell it what homeserver to connect to *by default*. Users will be
able to use a different homeserver if they like, though this can be disabled with `"disable_custom_urls": false` in your
config.
One of the following options **must** be supplied:
1. `default_server_config`: The preferred method of setting the homeserver connection information. Simply copy/paste
your [`/.well-known/matrix/client`](https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient)
into this field. For example:
```json
{
"default_server_config": {
"m.homeserver": {
"base_url": "https://matrix-client.matrix.org"
},
"m.identity_server": {
"base_url": "https://vector.im"
}
}
}
```
2. `default_server_name`: A different method of connecting to the homeserver by looking up the connection information
using `.well-known`. When using this option, simply use your server's domain name (the part at the end of user IDs):
`"default_server_name": "matrix.org"`
3. <del>`default_hs_url` and (optionally) `default_is_url`</del>: A very deprecated method of defining the connection
information. These are the same values seen as `base_url` in the `default_server_config` example, with `default_is_url`
being optional.
If a combination of these three methods is used then Element will fail to load. This is because it is unclear which
should be considered "first".
## Labs flags
Labs flags are optional, typically beta or in-development, features that can be turned on or off. The full range of
labs flags and their development status are documented [here](./labs.md). If interested, the feature flag process is
documented [here](./feature-flags.md).
To force a labs flag on or off, use the following:
```json
{
"features": {
"feature_you_want_to_turn_on": true,
"feature_you_want_to_keep_off": false
}
}
```
If you'd like the user to be able to self-select which labs flags they can turn on, add `"show_labs_flags": true` to
your config. This will turn on the tab in user settings.
**Note**: Feature support varies release-by-release. Check the [labs flag documentation](./labs.md) frequently if enabling
the functionality.
## Default settings
Some settings additionally support being specified at the config level to affect the user experience of your Element Web
instance. As of writing those settings are not fully documented, however a few are:
1. `default_federate`: When `true` (default), rooms will be marked as "federatable" during creation. Typically this setting
shouldn't be used as the federation capabilities of a room **cannot** be changed after the room is created.
2. `default_country_code`: An optional ISO 3166 alpha2 country code (eg: `GB`, the default) to use when showing phone number
inputs.
3. `room_directory`: Optionally defines how the room directory component behaves. Currently only a single property, `servers`
is supported to add additional servers to the dropdown. For example:
```json
{
"room_directory": {
"servers": ["matrix.org", "example.org"]
}
}
```
4. `setting_defaults`: Optional configuration for settings which are not described by this document and support the `config`
level. This list is incomplete. For example:
```json
{
"setting_defaults": {
"MessageComposerInput.showStickersButton": false,
"MessageComposerInput.showPollsButton": false
}
}
```
These values will take priority over the hardcoded defaults for the settings.
## Customisation & branding
<!-- Author's note: https://english.stackexchange.com/questions/570116/alternative-ways-of-saying-white-labeled -->
Element supports some customisation of the user experience through various branding and theme options. While it doesn't support
complete re-branding/private labeling, a more personalised experience can be achieved for your users.
1. `default_theme`: Typically either `light` (the default) or `dark`, this is the optional name of the colour theme to use.
If using custom themes, this can be a theme name from that as well.
2. `default_device_display_name`: Optional public name for devices created by login and registration, instead of the default
templated string. Note that this option does not support templating, currently.
3. `brand`: Optional name for the app. Defaults to `Element`. This is used throughout the application in various strings/locations.
4. `permalink_prefix`: An optional URL pointing to an Element Web deployment. For example, `https://app.element.io`. This will
change all permalinks (via the "Share" menus) to point at the Element Web deployment rather than `matrix.to`.
5. `desktop_builds`: Optional. Where the desktop builds for the application are, if available. This is explained in more detail
down below.
6. `mobile_builds`: Optional. Like `desktop_builds`, except for the mobile apps. Also described in more detail down below.
7. `mobile_guide_toast`: When `true` (default), users accessing the Element Web instance from a mobile device will be prompted to
download the app instead.
8. `update_base_url`: For the desktop app only, the URL where to acquire update packages. If specified, must be a path to a directory
containing `macos` and `win32` directories, with the update packages within. Defaults to `https://packages.element.io/desktop/update/`
in production.
9. `map_style_url`: Map tile server style URL for location sharing. e.g. `https://api.maptiler.com/maps/streets/style.json?key=YOUR_KEY_GOES_HERE`
This setting is ignored if your homeserver provides `/.well-known/matrix/client` in its well-known location, and the JSON file
at that location has a key `m.tile_server` (or the unstable version `org.matrix.msc3488.tile_server`). In this case, the
configuration found in the well-known location is used instead.
10. `welcome_user_id`: An optional user ID to start a DM with after creating an account. Defaults to nothing (no DM created).
11. `custom_translations_url`: An optional URL to allow overriding of translatable strings. The JSON file must be in a format of
`{"affected string": {"languageCode": "new string"}}`. See https://github.com/matrix-org/matrix-react-sdk/pull/7886 for details.
12. `branding`: Options for configuring various assets used within the app. Described in more detail down below.
13. `embedded_pages`: Further optional URLs for various assets used within the app. Described in more detail down below.
14. `disable_3pid_login`: When `false` (default), **enables** the options to log in with email address or phone number. Set to
`true` to hide these options.
15. `disable_login_language_selector`: When `false` (default), **enables** the language selector on the login pages. Set to `true`
to hide this dropdown.
16. `disable_guests`: When `false` (default), **enable** guest-related functionality (peeking/previewing rooms, etc) for unregistered
users. Set to `true` to disable this functionality.
### `desktop_builds` and `mobile_builds`
These two options describe the various availability for the application. When the app needs to promote an alternative download,
such as trying to get the user to use an Android app or the desktop app for encrypted search, the config options will be looked
at to see if the link should be to somewhere else.
Starting with `desktop_builds`, the following subproperties are available:
1. `available`: Required. When `true`, the desktop app can be downloaded from somewhere.
2. `logo`: Required. A URL to a logo (SVG), intended to be shown at 24x24 pixels.
3. `url`: Required. The download URL for the app. This is used as a hyperlink.
When `desktop_builds` is not specified at all, the app will assume desktop downloads are available from https://element.io
For `mobile_builds`, the following subproperties are available:
1. `ios`: The URL for where to download the iOS app, such as an App Store link. When explicitly `null`, the app will assume the
iOS app cannot be downloaded. When not provided, the default Element app will be assumed available.
2. `android`: The same as `ios`, except for Android instead.
3. `fdroid`: The same as `android`, except for FDroid instead.
Together, these two options might look like the following in your config:
```json
{
"desktop_builds": {
"available": true,
"logo": "https://example.org/assets/logo-small.svg",
"url": "https://example.org/not_element/download"
},
"mobile_builds": {
"ios": null,
"android": "https://example.org/not_element/android",
"fdroid": "https://example.org/not_element/fdroid"
}
}
```
### `branding` and `embedded_pages`
These two options point at various URLs for changing different internal pages (like the welcome page) and logos within the
application.
Starting with `branding`, the following subproperties are available:
1. `welcome_background_url`: When a string, the URL for the full-page image background of the login, registration, and welcome
pages. This property can additionally be an array to have the app choose an image at random from the selections.
2. `auth_header_logo_url`: A URL to the logo used on the login, registration, etc pages.
3. `auth_footer_links`: A list of links to add to the footer during login, registration, etc. Each entry must have a `text` and
`url` property.
`embedded_pages` can be configured as such:
1. `welcome_url`: A URL to an HTML page to show as a welcome page (landing on `#/welcome`). When not specified, the default
`welcome.html` that ships with Element will be used instead.
2. `home_url`: A URL to an HTML page to show within the app as the "home" page. When the app doesn't have a room/screen to
show the user, it will use the home page instead. The home page is additionally accessible from the user menu. By default,
no home page is set and therefore a hardcoded landing screen is used.
3. `login_for_welcome`: When `true` (default `false`), the app will use the login form as a welcome page instead of the welcome
page itself. This disables use of `welcome_url` and all welcome page functionality.
Together, the options might look like this in your config:
```json
{
"branding": {
"welcome_background_url": "https://example.org/assets/background.jpg",
"auth_header_logo_url": "https://example.org/assets/logo.svg",
"auth_footer_links": [
{"text": "FAQ", "url": "https://example.org/faq"},
{"text": "Donate", "url": "https://example.org/donate"},
]
},
"embedded_pages": {
"welcome_url": "https://example.org/assets/welcome.html",
"home_url": "https://example.org/assets/home.html"
}
}
```
Note that `index.html` also has an og:image meta tag that is set to an image hosted on element.io. This is the image used if
links to your copy of Element appear in some websites like Facebook, and indeed Element itself. This has to be static in the HTML
and an absolute URL (and HTTP rather than HTTPS), so it's not possible for this to be an option in config.json. If you'd like to
change it, you can build Element, but run `RIOT_OG_IMAGE_URL="http://example.com/logo.png" yarn build`. Alternatively, you can edit
the `og:image` meta tag in `index.html` directly each time you download a new version of Element.
## SSO setup
When Element is deployed alongside a homeserver with SSO-only login, some options to ease the user experience might want to be set:
1. `logout_redirect_url`: Optional URL to redirect the user to after they have logged out. Some SSO systems support a page that the
user can be sent to in order to log them out of that system too, making logout symmetric between Element and the SSO system.
2. `sso_redirect_options`: Options to define how to handle unauthenticated users. If the object contains `"immediate": true`, then
all unauthenticated users will be automatically redirected to the SSO system to start their login. If instead you'd only like to
have users which land on the welcome page to be redirected, use `"on_welcome_page": true`. As an example:
```json
{
"sso_redirect_options": {
"immediate": false,
"on_welcome_page": true
}
}
```
It is most common to use the `immediate` flag instead of `on_welcome_page`.
## VoIP / Jitsi calls
Currently, Element uses Jitsi to offer conference calls in rooms. A set of defaults are applied, pointing at our Jitsi instance,
to ensure conference calling works, however you can point Element at your own Jitsi if you prefer.
More information about the Jitsi setup can be found [here](./jitsi.md).
The VoIP and Jitsi options are:
1. `jitsi`: Optional configuration for how to start Jitsi conferences. Currently can only contain a single `preferred_domain`
value which points at the domain of the Jitsi instance. Defaults to `meet.element.io`. This is *not* used if the Jitsi widget
was created by an integration manager, or if the homeserver provides Jitsi information in `/.well-known/matrix/client`. For
example:
```json
{
"jitsi": {
"preferred_domain": "meet.jit.si"
}
}
```
2. `jitsi_widget`: Optional configuration for the built-in Jitsi widget. Currently can only contain a single `skip_built_in_welcome_screen`
value, denoting whether the "Join Conference" button should be shown. When `true` (default `false`), Jitsi calls will skip to
the call instead of having a screen with a single button on it. This is most useful if the Jitsi instance being used already
has a landing page for users to test audio and video before joining the call, otherwise users will automatically join the call.
For example:
```json
{
"jitsi_widget": {
"skip_built_in_welcome_screen": true
}
}
```
3. `voip`: Optional configuration for various VoIP features. Currently can only contain a single `obey_asserted_identity` value to
send MSC3086-style asserted identity messages during VoIP calls in the room corresponding to the asserted identity. This *must*
only be set in trusted environments. The option defaults to `false`. For example:
```json
{
"voip": {
"obey_asserted_identity": false
}
}
```
4. `widget_build_url`: Optional URL to have Element make a request to when a user presses the voice/video call buttons in the app,
if a call would normally be started by the action. The URL will be called with a `roomId` query parameter to identify the room
being called in. The URL must respond with a JSON object similar to the following:
```json
{
"widget_id": "$arbitrary_string",
"widget": {
"creatorUserId": "@user:example.org",
"id": "$the_same_widget_id",
"type": "m.custom",
"waitForIframeLoad": true,
"name": "My Widget Name Here",
"avatar_url": "mxc://example.org/abc123",
"url": "https://example.org/widget.html",
"data": {
"title": "Subtitle goes here"
}
},
"layout": {
"container": "top",
"index": 0,
"width": 65,
"height": 50
}
}
```
The `widget` is the `content` of a normal widget state event. The `layout` is the layout specifier for the widget being created,
as defined by the `io.element.widgets.layout` state event.
5. `audio_stream_url`: Optional URL to pass to Jitsi to enable live streaming. This option is considered experimental and may be removed
at any time without notice.
## Bug reporting
If you run your own rageshake server to collect bug reports, the following options may be of interest:
1. `bug_report_endpoint_url`: URL for where to submit rageshake logs to. Rageshakes include feedback submissions and bug reports. When
not present in the config, the app will disable all rageshake functionality. Set to `https://element.io/bugreports/submit` to submit
rageshakes to us, or use your own rageshake server.
2. `uisi_autorageshake_app`: If a user has enabled the "automatically send debug logs on decryption errors" flag, this option will be sent
alongside the rageshake so the rageshake server can filter them by app name. By default, this will be `element-web`, as with any other
rageshake submitted by the app.
If you are using the element.io rageshake server, please set this to `element-auto-uisi` so we can better filter them.
If you would like to use [Sentry](https://sentry.io/) for rageshake data, add a `sentry` object to your config with the following values:
1. `dsn`: The Sentry [DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/).
2. `environment`: Optional [environment](https://docs.sentry.io/product/sentry-basics/environments/) to pass to Sentry.
For example:
```json
{
"sentry": {
"dsn": "dsn-goes-here",
"environment": "production"
}
}
```
## Integration managers
Integration managers are embedded applications within Element to help the user configure bots, bridges, and widgets. An integration manager
is a separate piece of software not typically available with your homeserver. To disable integrations, leave the options defined here out of
your config.
1. `integrations_ui_url`: The UI URL for the integration manager.
2. `integrations_rest_url`: The REST interface URL for the integration manager.
3. `integrations_widgets_urls`: A list of URLs the integration manager uses to host widgets.
If you would like to use Scalar, the integration manager maintained by Element, the following options would apply:
```json
{
"integrations_ui_url": "https://scalar.vector.im/",
"integrations_rest_url": "https://scalar.vector.im/api",
"integrations_widgets_urls": [
"https://scalar.vector.im/_matrix/integrations/v1",
"https://scalar.vector.im/api",
"https://scalar-staging.vector.im/_matrix/integrations/v1",
"https://scalar-staging.vector.im/api",
"https://scalar-staging.riot.im/scalar/api"
]
}
```
## Administrative options
If you would like to include a custom message when someone is reporting an event, set the following Markdown-capable field:
```json
{
"report_event": {
"admin_message_md": "Please be sure to review our [terms of service](https://example.org/terms) before reporting a message."
}
}
```
To add additional "terms and conditions" links throughout the app, use the following template:
```json
{
"terms_and_conditions_links": [
{ "text": "Code of conduct", "url": "https://example.org/code-of-conduct" }
]
}
```
## Analytics
Analytics are currently possible with two systems: `posthog` (preferred) and <del>`piwik`</del> (matomo; deprecated). When
these configuration options are not present, analytics are deemed impossible and the user won't be asked to opt-in to the
system.
To configure [Posthog](https://posthog.com/), add the following under `posthog` in your config:
1. `api_host`: The hostname of the posthog server.
2. `project_api_key`: The API key from posthog.
To configure Piwik (***DEPRECATED***), add the following under `piwik` in your config:
1. `url`: The URL of the piwik server.
2. `site_id`: The site ID to use.
3. `policy_url`: URL to the analytics collection policy.
4. `whitelisted_hs_urls`: A list of homeserver client-server URLs to *not* redact from analytics.
Additionally, you may set `"piwik": false` to disable piwik configuration too. An `analytics_owner` can also be specified in your
config to replace the company name used in dialogs talking about analytics - this defaults to `brand`, and is useful when the
provider of analytics is different from the provider of the Element instance.
## Server hosting links
If you would like to encourage matrix.org users to sign up for a service like [Element Matrix Services](https://element.io/matrix-services/server-hosting),
the following configuration options can be set. Note that if the options are missing from the configuration then the hosting prompts
will not be shown to the user.
1. `hosting_signup_link`: Optional URL to link the user to when talking about "Upgrading your account". Will contain a query parameter
of `utm_campaign` to denote which link the user clicked on within the app. Only ever applies to matrix.org users specifically.
2. `host_signup`: Optional configuration for an account importer to your hosting platform. The API surface of this is not documented
at the moment, but can be configured with the following subproperties:
1. `brand`: The brand name to use.
2. `url`: The iframe URL for the importer.
3. `domains`: The homeserver domains to show the importer to.
4. `cookie_policy_url`: The URL to the cookie policy for the importer.
5. `privacy_policy_url`: The URL to the privacy policy for the importer.
6. `terms_of_service_url`: The URL to the terms of service for the importer.
If you're looking to mirror a setup from our production/development environments, the following config should be used:
```json
{
"hosting_signup_link": "https://element.io/matrix-services?utm_source=element-web&utm_medium=web",
"host_signup": {
"brand": "Element Home",
"domains": [ "matrix.org" ],
"url": "https://ems.element.io/element-home/in-app-loader",
"cookie_policy_url": "https://element.io/cookie-policy",
"privacy_policy_url": "https://element.io/privacy",
"terms_of_service_url": "https://element.io/terms-of-service"
}
}
```
## Miscellaneous
Element supports other options which don't quite fit into other sections of this document.
To configure whether presence UI is shown for a given homeserver, set `enable_presence_by_hs_url`. It is recommended to
set this value to the following at a minimum:
```json
{
"enable_presence_by_hs_url": {
"https://matrix.org": false,
"https://matrix-client.matrix.org": false
}
}
```
## Identity servers
The identity server is used for inviting other users to a room via third party
identifiers like emails and phone numbers. It is not used to store your password
@ -232,16 +488,14 @@ Currently, the only two public identity servers are https://vector.im and
https://matrix.org, however in the future identity servers will be
decentralised.
Desktop app configuration
=========================
## Desktop app configuration
See https://github.com/vector-im/element-desktop#user-specified-configjson
UI Features
===========
## UI Features
Parts of the UI can be disabled using UI features. These are settings which appear
under `settingDefaults` and can only be `true` (default) or `false`. When `false`,
under `setting_defaults` and can only be `true` (default) or `false`. When `false`,
parts of the UI relating to that feature will be disabled regardless of the user's
preferences.
@ -277,4 +531,14 @@ Currently, the following UI feature flags are supported:
user.
* `UIFeature.roomHistorySettings` - Whether or not the room history settings are shown to the user.
This should only be used if the room history visibility options are managed by the server.
* `UIFeature.TimelineEnableRelativeDates` - Display relative date separators (eg: 'Today', 'Yesterday') in the timeline for recent messages. When false day dates will be used.
* `UIFeature.TimelineEnableRelativeDates` - Display relative date separators (eg: 'Today', 'Yesterday') in the
timeline for recent messages. When false day dates will be used.
## Undocumented / developer options
The following are undocumented or intended for developer use only.
1. `fallback_hs_url`
2. `sync_timeline_limit`
3. `dangerously_allow_unsafe_and_insecure_passwords`
4. `latex_maths_delims`