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 entriesby 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",
            "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, alabeland 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 lightboxTemplateproperty.
*-lightbox No No Any position with a “-lightbox” suffix can be used for loading custom lightbox content. SeeopenLightbox() 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, desktoporall.
url The URL from which to load the position. This URL will be loaded through asigned 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 may be a full URL to the icon, or (preferably) a Unicode codepoint in the Font Awesome font set:http://fortawesome.github.io/Font-Awesome/icons/
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 ofclosepresents 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.