Diff

mod_invites_page/README.markdown @ 4094:dd00a2b9927c

mod_invites_page: New module to generate landing page for invites
author Matthew Wild <mwild1@gmail.com>
date Fri, 11 Sep 2020 13:52:32 +0100
child 4104:476afcbfb3e9
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_invites_page/README.markdown	Fri Sep 11 13:52:32 2020 +0100
@@ -0,0 +1,53 @@
+---
+labels:
+- 'Stage-Beta'
+summary: 'Generate friendly web page for invitations'
+...
+
+Introduction
+============
+
+This module is part of the suite of modules that implement invite-based
+account registration for Prosody. The other modules are:
+
+- mod_invites
+- mod_invites_adhoc
+- mod_invites_register
+- mod_invites_register_web
+- mod_register_apps
+
+For details and a full overview, start with the mod_invites documentation.
+
+Details
+=======
+
+mod_invites_page provides a unique web page for each generated invitation.
+Without this module, Prosody will only be able to generate invite links as
+`xmpp:` URIs (they look something like `xmpp:example.com?register;preauth=29Xbxr91`).
+URIs will only work if the invited user already has an XMPP client installed.
+This is usually not the case.
+
+This module transforms the URI into a friendly web page that can be shared
+via any method (email, SMS, etc.), and opened in any browser. The page explains
+the invitation and guides the user to set up their account using one of a
+configurable list of XMPP clients (to configure the list, see mod_register_apps
+documentation).
+
+Configuration
+=============
+
+| Name                      | Description                                                                    | Default                                                    |
+|---------------------------|--------------------------------------------------------------------------------|------------------------------------------------------------|
+| invites_page              | The format of an invite page URL (must begin with `https://`)                  | `"https://{host}:5281/invites_page?{invite.token}"`        |
+| invites_registration_page | The format of an invite registration page URL (may be relative to invites_page)| `"register?t={invite.token}&c={app.id}"`                   |
+|                           |                                                                                | site_name                 | The friendly name of the server| `"example.com"` |
+
+The `invites_page` and `invites_registration_page` options are templates
+that support a number of variables. The most useful being `{host}` and
+`{invite.token}`.
+
+All the usual [HTTP configuration options](https://prosody.im/doc/http)
+can be used to configure this module. In particular, if you run Prosody
+behind a reverse proxy such as nginx or Apache, you will probably want
+to set `http_external_url` so that Prosody knows what URLs should look
+like for users.