Mercurial > prosody-modules

comparison mod_register_apps/README.markdown @ 4110:fdc84741258d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_register_apps: Add missing docs
author Matthew Wild <mwild1@gmail.com>
date Fri, 11 Sep 2020 16:57:09 +0100
parents
children c85af57e82e0
comparison
equal deleted inserted replaced
4109:70af86f54704 4110:fdc84741258d
1 ---
2 labels:
3 - 'Stage-Beta'
4 summary: 'Manage list of compatible client apps'
5 ...
6
7 Introduction
8 ============
9
10 This module provides a way to configure a list of XMPP client apps recommended
11 by the current server. This list is used by other modules such as mod_invites_page
12 and mod_invites_register_web.
13
14 It also contains the logos of a number of popular XMPP clients, and serves
15 them over HTTP for other modules to reference when serving web pages.
16
17 # Configuration
18
19 There is one configuration option, `site_apps`, which contains the list
20 of apps and their metadata.
21
22 ``` {.lua}
23 -- Example site_apps config with two clients
24 site_apps = {
25 {
26 name = "Conversations";
27 text = [[Conversations is a Jabber/XMPP client for Android 4.0+ smartphones that has been optimized to provide a unique mobile experience.]];
28 image = "assets/logos/conversations.svg";
29 link = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
30 platforms = { "Android" };
31 supports_preauth_uri = true;
32 magic_link_format = "{app.link!}&referrer={invite.uri}";
33 download = {
34 buttons = {
35 {
36 image = "https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png";
37 url = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
38 };
39 };
40 };
41 };
42 {
43 name = "Gajim";
44 text = [[A fully-featured desktop chat client for Windows and Linux.]];
45 image = "assets/logos/gajim.svg";
46 link = "https://gajim.org/";
47 platforms = { "Windows", "Linux" };
48 download = {
49 buttons = {
50 {
51 text = "Download Gajim";
52 url = "https://gajim.org/download/";
53 target = "_blank";
54 };
55 };
56 };
57 };
58 }
59 ```
60 The fields of each client entry are as follows:
61
62 | Field | Description |
63 |----------------------|--------------------------------------------------------------------------|
64 | name | The name of the client |
65 | text | Description of the client |
66 | image | URL to a logo for the client, may also be a path in the assets/ directory|
67 | link | URL to the app |
68 | platforms | A list of platforms the app can be installed on |
69 | supports_preauth_uri | `true` if the client supports XEP-0401 preauth URIs |
70 | magic_link_format | A template to generate a magic installation link from an invite |
71 | download | Download instructions and buttons, described below |
72
73 ## Download metadata
74
75 The `download` field supports an optional text prompt and one or more buttons.
76 Each button must contain either a `text` or `image` field and must contain
77 a `url` field. It is recommended to set `target = "_blank"` if the link
78 opens a new page, so that the user doesn't lose the invite page.
79
80 Example download field with instructions and two buttons:
81
82 ``` {.lua}
83 download = {
84 text = "Some optional instructions about downloading the client...";
85 buttons = {
86 {
87 text = "Button 1: some text";
88 url = "https://example.com/";
89 };
90 {
91 image = "https://example.com/button2.png";
92 url = "https://example.com/download/";
93 };
94 };
95 }
96
97 ```