view mod_register_apps/README.markdown @ 4976:75b6e5df65f9

various: Improve error reporting if missing file server module on 0.12 If there is some error loading net.http.files then it would be swallowed by the pcall and then it would proceed to trying mod_http_files, which might cause unexpected behavior on 0.12 Ref #1765
author Kim Alvefur <zash@zash.se>
date Mon, 18 Jul 2022 22:47:54 +0200
parents ad9ce6750880
children
line wrap: on
line source

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

```