mod_register_apps

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.

-- 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:

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/";
        };
    };
}