Configuring Application manifest.json

Each application has a manifest.json which specifies meta-data about the application. Meta-data included are the name and icon used for listing the application in the Speakap Market, and the entries by which the application can be accessed. Here is an example manifest:

{
    "name": {
        "en-US": "Speakap Example Manifest",
        "nl-NL": "Speakap voorbeeldmanifest"
    },
    "icon": "https://example.app.speakap.io/icon.png",
    "iconThumbnailUrl": "https://example.app.speakap.io/icon_thumbnail.png",
    "permissions": ["send_alerts"],
    "entries": [
        {
            "position": "main",
            "devices": "all",
            "url": "https://example.app.speakap.io/",
            "label": {
                "en-US": "Example app",
                "nl-NL": "Voorbeeld-app"
            },
            "icon": "\uf073"
        },
        {
            "position": "network-timeline-widget",
            "devices": "all",
            "url": "https://example.app.speakap.io/widget",
            "height": "200",
            "label": {
                "en-US": "Example widget",
                "nl-NL": "Voorbeeld-widget"
            }
        },
        {
            "position": "install-wizard",
            "devices": "all",
            "url": "https://example.app.speakap.io/install"
        }
    ]
}

The most generic information are the name and icon, both of which are used for representing the application in the Speakap Market. For the name, as well as entry labels, it is important to have translations for every language relevant to the audience of your application. The “en-US” translation is always required as it will be used to present the name and labels to anyone using Speakap in a language for which the application does not provide an appropriate translation.

The iconThumbnailUrl is used to present data posted by the application. For example, applications can be given permissions to post timeline updates, but normally every update has a thumbnail of the author displayed next to it. For updates posted by applications, the thumbnail icon of the application will be used instead.

The meat of the manifest is provided by the definitions of the entries. At least one entry should be provided, because without it the application would never be visible to the user, nor have any way of knowing it’s installed in the first place. Every entry has a position and a url, and optionally devices, a label and an icon may be provided. First, we’ll explain the different positions:

Position	Label?	Icon?	Description
main	Yes	Yes	The main position for applications is presented to the user when the user clicks on an application in the left-menu in the Speakap web application or a Speakap mobile application.
network-timeline-widget	Yes	No	The network timeline widget is a position among the list of widgets that are displayed on the right-hand side of the network timeline (the “homepage” of the Speakap web application). This position is not available on mobile.
install-wizard	No	No	The installation wizard is presented when the application is installed by the network administrator. More about this can be found in the tutorial for creating an installation wizard.
settings-page	No	No	The settings page is used for configuring the application after it has been installed. It works the same as the “install-wizard” position, but has the option to select a different lightbox template through the lightboxTemplate property.
*-lightbox	No	No	Any position with a “-lightbox” suffix can be used for loading custom lightbox content. See openLightbox() for more information.

Before we continue, we’ll also explain all the properties allowed for defining an entry:

Property	Description
position	The position to which the entry applies (see table above).
permissions	An array with permissions that the application requires. See Application Permissions.
devices	The devices to which the entry applies. One of `phone`, `tablet`, `desktop` or `all`.
url	The URL from which to load the position. This URL will be loaded through a signed request.
label	The user-visible label to present the application entry. This should be specified as a dictionary of translations (see example).
icon	The user-visible icon to present the application entry. This must be a Unicode codepoint in the Speakap iconset (check show codes to see the unicodes)
lightboxTemplate	Only applicable to the settings-page position, this property defines what kind of lightbox should be used for hosting the position. A value of `save-cancel` (the default) presents a lightbox with Save and Cancel buttons. A value of `close` presents a lightbox with just a single Close button.

Now you have an understanding of the properties that can be specified and the positions for which you create manifest entries, it is important to realize it is the combination of the position and the devices that define an entry. For example, you may specify one entry for the “main” position for “all” devices as in the example above, but if you wish to use different URL endpoints for providing an optimized experience for different form factors, you may specify three entries for the “main” position, one for “phone” devices, one for “tablet” devices and one for “desktop” devices.