File

---
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/";
        };
    };
}

```