prosody-modules
tip
mod_register_apps/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_register_apps/README.md @ 6211:750d64c47ec6 draft default tip

Merge
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Tue, 18 Mar 2025 00:31:36 +0700
parent 6003:fe081789f7b5
comparison
equal deleted inserted replaced
6210:24316a399978 6211:750d64c47ec6
1 ---
2 labels:
3 - 'Stage-Beta'
4 summary: 'Manage list of compatible client apps'
5 rockspec:
6 build:
7 copy_directories:
8 - assets
9 ...
10
11 Introduction
12 ============
13
14 This module provides a way to configure a list of XMPP client apps recommended
15 by the current server. This list is used by other modules such as mod_invites_page
16 and mod_invites_register_web.
17
18 It also contains the logos of a number of popular XMPP clients, and serves
19 them over HTTP for other modules to reference when serving web pages.
20
21 # Configuration
22
23 | Field | Description |
24 |----------------------|--------------------------------------------------------------------------|
25 | site_apps | A list of apps and their metadata |
26 | site_apps_show | A list of app ids to only show |
27 | site_apps_hide | A list of app ids to never show |
28
29 An "app id" is the lower case app name, with any spaces replaced by `-`. E.g. "My Chat" would be `"my-chat"`.
30
31 The module comes with a preconfigured `site_apps` containing popular clients. Patches are welcome to
32 add/update this list as needed!
33
34 If you want to limit to just displaying a subset of the apps on your server, use the `site_apps_show`
35 option, e.g. `site_apps_show = { "conversations", "siskin-im" }`. To never show specific apps, you
36 can use `site_apps_hide`, e.g. `site_apps_hide = { "pidgin" }`.
37
38 # App metadata format
39
40 The configuration option `site_apps` contains the list
41 of apps and their metadata.
42
43 ``` {.lua}
44 -- Example site_apps config with two clients
45 site_apps = {
46 {
47 name = "Conversations";
48 text = [[Conversations is a Jabber/XMPP client for Android 4.0+ smartphones that has been optimized to provide a unique mobile experience.]];
49 image = "assets/logos/conversations.svg";
50 link = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
51 platforms = { "Android" };
52 supports_preauth_uri = true;
53 magic_link_format = "{app.link!}&referrer={invite.uri}";
54 download = {
55 buttons = {
56 {
57 image = "https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png";
58 url = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
59 };
60 };
61 };
62 };
63 {
64 name = "Gajim";
65 text = [[A fully-featured desktop chat client for Windows and Linux.]];
66 image = "assets/logos/gajim.svg";
67 link = "https://gajim.org/";
68 platforms = { "Windows", "Linux" };
69 download = {
70 buttons = {
71 {
72 text = "Download Gajim";
73 url = "https://gajim.org/download/";
74 target = "_blank";
75 };
76 };
77 };
78 };
79 }
80 ```
81 The fields of each client entry are as follows:
82
83 | Field | Description |
84 |----------------------|--------------------------------------------------------------------------|
85 | name | The name of the client |
86 | text | Description of the client |
87 | image | URL to a logo for the client, may also be a path in the assets/ directory|
88 | link | URL to the app |
89 | platforms | A list of platforms the app can be installed on |
90 | supports_preauth_uri | `true` if the client supports XEP-0401 preauth URIs |
91 | magic_link_format | A template to generate a magic installation link from an invite |
92 | download | Download instructions and buttons, described below |
93
94 ## Download metadata
95
96 The `download` field supports an optional text prompt and one or more buttons.
97 Each button must contain either a `text` or `image` field and must contain
98 a `url` field. It is recommended to set `target = "_blank"` if the link
99 opens a new page, so that the user doesn't lose the invite page.
100
101 Example download field with instructions and two buttons:
102
103 ``` {.lua}
104 download = {
105 text = "Some optional instructions about downloading the client...";
106 buttons = {
107 {
108 text = "Button 1: some text";
109 url = "https://example.com/";
110 };
111 {
112 image = "https://example.com/button2.png";
113 url = "https://example.com/download/";
114 };
115 };
116 }
117
118 ```