--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_register_apps/README.markdown Fri Sep 11 16:57:09 2020 +0100
@@ -0,0 +1,97 @@
+---
+labels:
+- 'Stage-Beta'
+summary: 'Manage list of compatible client apps'
+...
+
+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
+
+There is one configuration option, `site_apps`, which 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/";
+ };
+ };
+}
+
+```