Mercurial > prosody-modules

annotate mod_register_apps/README.markdown @ 5516:f25df3af02c1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_client_management: Include client software version number in listing Should you ever wish to revoke a client by version number, e.g. for security reasons affecting certain versions, then it would be good to at the very least see which version is used. Also includes the OAuth2 software ID, an optional unique identifier that should be the same for all installations of a particular software.
author Kim Alvefur <zash@zash.se>
date Sat, 03 Jun 2023 19:21:39 +0200
parents ad9ce6750880
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
4110
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels:
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 - 'Stage-Beta'
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'Manage list of compatible client apps'
4183
ad9ce6750880 mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents: 4113
diff changeset
5 rockspec:
ad9ce6750880 mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents: 4113
diff changeset
6 build:
ad9ce6750880 mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents: 4113
diff changeset
7 copy_directories:
ad9ce6750880 mod_register_apps: Point out assets/ directory for packaging
Kim Alvefur <zash@zash.se>
parents: 4113
diff changeset
8 - assets
4110
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 ...
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 Introduction
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 ============
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 This module provides a way to configure a list of XMPP client apps recommended
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15 by the current server. This list is used by other modules such as mod_invites_page
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16 and mod_invites_register_web.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 It also contains the logos of a number of popular XMPP clients, and serves
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 them over HTTP for other modules to reference when serving web pages.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 # Configuration
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
4113
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
23 | Field | Description |
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
24 |----------------------|--------------------------------------------------------------------------|
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
25 | site_apps | A list of apps and their metadata |
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
26 | site_apps_show | A list of app ids to only show |
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
27 | site_apps_hide | A list of app ids to never show |
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
28
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
29 An "app id" is the lower case app name, with any spaces replaced by `-`. E.g. "My Chat" would be `"my-chat"`.
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
30
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
31 The module comes with a preconfigured `site_apps` containing popular clients. Patches are welcome to
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
32 add/update this list as needed!
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
33
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
34 If you want to limit to just displaying a subset of the apps on your server, use the `site_apps_show`
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
35 option, e.g. `site_apps_show = { "conversations", "siskin-im" }`. To never show specific apps, you
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
36 can use `site_apps_hide`, e.g. `site_apps_hide = { "pidgin" }`.
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
37
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
38 # App metadata format
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
39
c85af57e82e0 mod_register_apps: Add site_apps_show and site_apps_hide options (thanks meaz)
Matthew Wild <mwild1@gmail.com>
parents: 4110
diff changeset
40 The configuration option `site_apps` contains the list
4110
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 of apps and their metadata.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 ``` {.lua}
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 -- Example site_apps config with two clients
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 site_apps = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47 name = "Conversations";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 text = [[Conversations is a Jabber/XMPP client for Android 4.0+ smartphones that has been optimized to provide a unique mobile experience.]];
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 image = "assets/logos/conversations.svg";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50 link = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51 platforms = { "Android" };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 supports_preauth_uri = true;
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53 magic_link_format = "{app.link!}&referrer={invite.uri}";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 download = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 buttons = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 image = "https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 url = "https://play.google.com/store/apps/details?id=eu.siacs.conversations";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 name = "Gajim";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 text = [[A fully-featured desktop chat client for Windows and Linux.]];
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 image = "assets/logos/gajim.svg";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 link = "https://gajim.org/";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 platforms = { "Windows", "Linux" };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69 download = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 buttons = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72 text = "Download Gajim";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 url = "https://gajim.org/download/";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 target = "_blank";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79 }
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
80 ```
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
81 The fields of each client entry are as follows:
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
82
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
83 | Field | Description |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
84 |----------------------|--------------------------------------------------------------------------|
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
85 | name | The name of the client |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
86 | text | Description of the client |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
87 | image | URL to a logo for the client, may also be a path in the assets/ directory|
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
88 | link | URL to the app |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
89 | platforms | A list of platforms the app can be installed on |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
90 | supports_preauth_uri | `true` if the client supports XEP-0401 preauth URIs |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
91 | magic_link_format | A template to generate a magic installation link from an invite |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
92 | download | Download instructions and buttons, described below |
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
93
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
94 ## Download metadata
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
95
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
96 The `download` field supports an optional text prompt and one or more buttons.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
97 Each button must contain either a `text` or `image` field and must contain
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
98 a `url` field. It is recommended to set `target = "_blank"` if the link
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
99 opens a new page, so that the user doesn't lose the invite page.
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
100
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
101 Example download field with instructions and two buttons:
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
102
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
103 ``` {.lua}
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
104 download = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
105 text = "Some optional instructions about downloading the client...";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
106 buttons = {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
107 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
108 text = "Button 1: some text";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
109 url = "https://example.com/";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
110 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
111 {
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
112 image = "https://example.com/button2.png";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
113 url = "https://example.com/download/";
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
114 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
115 };
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
116 }
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
117
fdc84741258d mod_register_apps: Add missing docs
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
118 ```