Diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_register_apps/README.md	Tue Oct 22 10:26:01 2024 +0200
@@ -0,0 +1,118 @@
+---
+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/";
+        };
+    };
+}
+
+```