---
labels:
- 'Stage-Beta'
summary: 'Manage list of compatible client apps'
rockspec:
build:
copy_directories:
- assets
...
Introduction
============
This module provides a way to configure a list of XMPP client apps recommended
by the current server. This list is used by other modules such as mod_invites_page
and mod_invites_register_web.
It also contains the logos of a number of popular XMPP clients, and serves
them over HTTP for other modules to reference when serving web pages.
# Configuration
| Field | Description |
|----------------------|--------------------------------------------------------------------------|
| site_apps | A list of apps and their metadata |
| site_apps_show | A list of app ids to only show |
| site_apps_hide | A list of app ids to never show |
An "app id" is the lower case app name, with any spaces replaced by `-`. E.g. "My Chat" would be `"my-chat"`.
The module comes with a preconfigured `site_apps` containing popular clients. Patches are welcome to
add/update this list as needed!
If you want to limit to just displaying a subset of the apps on your server, use the `site_apps_show`
option, e.g. `site_apps_show = { "conversations", "siskin-im" }`. To never show specific apps, you
can use `site_apps_hide`, e.g. `site_apps_hide = { "pidgin" }`.
# App metadata format
The configuration option `site_apps` contains the list
of apps and their metadata.
``` {.lua}
-- Example site_apps config with two clients
site_apps = {
{
name = "Conversations";
text = [[Conversations is a Jabber/XMPP client for Android 4.0+ smartphones that has been optimized to provide a unique mobile experience.]];
image = "assets/logos/conversations.svg";
link = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
platforms = { "Android" };
supports_preauth_uri = true;
magic_link_format = "{app.link!}&referrer={invite.uri}";
download = {
buttons = {
{
image = "https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png";
url = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
};
};
};
};
{
name = "Gajim";
text = [[A fully-featured desktop chat client for Windows and Linux.]];
image = "assets/logos/gajim.svg";
link = "https://gajim.org/";
platforms = { "Windows", "Linux" };
download = {
buttons = {
{
text = "Download Gajim";
url = "https://gajim.org/download/";
target = "_blank";
};
};
};
};
}
```
The fields of each client entry are as follows:
| Field | Description |
|----------------------|--------------------------------------------------------------------------|
| name | The name of the client |
| text | Description of the client |
| image | URL to a logo for the client, may also be a path in the assets/ directory|
| link | URL to the app |
| platforms | A list of platforms the app can be installed on |
| supports_preauth_uri | `true` if the client supports XEP-0401 preauth URIs |
| magic_link_format | A template to generate a magic installation link from an invite |
| download | Download instructions and buttons, described below |
## Download metadata
The `download` field supports an optional text prompt and one or more buttons.
Each button must contain either a `text` or `image` field and must contain
a `url` field. It is recommended to set `target = "_blank"` if the link
opens a new page, so that the user doesn't lose the invite page.
Example download field with instructions and two buttons:
``` {.lua}
download = {
text = "Some optional instructions about downloading the client...";
buttons = {
{
text = "Button 1: some text";
url = "https://example.com/";
};
{
image = "https://example.com/button2.png";
url = "https://example.com/download/";
};
};
}
```