App manifest

An App manifest is the file in which an App says what it is: its name, who publishes it, where it is served, how it signs in and what it asks for. The file is called awhere-app.json. An App is installed from its manifest.

Installing an App does two things: it writes one row for the App, which keeps the manifest as it was installed, and it makes the App's OAuth client. Uninstalling takes both back, and installing again restores the same client with the same secret.

An App serves its own manifest at awhere-app.json under its address. When an administrator previews an install, the platform asks the App for that file and warns if it does not answer, if it is not readable, or if its id or version differs from the manifest being installed.

An exampleCopy Anchor Link

This is the manifest of Map Studio, as the App publishes it. It uses the required fields and a few optional ones.

{
  "manifestVersion": 1,
  "id": "map-studio",
  "name": "Map Studio",
  "shortName": "Map",
  "description": "Web maps with layers, styles and measurement.",
  "locales": {
    "th": { "description": "สร้างแผนที่เว็บที่มีชั้นข้อมูล รูปแบบการแสดงผล และเครื่องมือวัด" }
  },
  "publisher": {
    "name": "MAPBOSS Co., Ltd.",
    "url": "https://mapboss.co.th"
  },
  "channel": "official",
  "version": "1.0.0",
  "categories": ["maps"],
  "path": "/map-studio/",
  "oauth": {
    "scopes": ["*"]
  }
}

Required fieldsCopy Anchor Link

A manifest without every field below is refused, and the reason names the field.

Optional fieldsCopy Anchor Link

A key that is not in these two tables is dropped, and image is reserved and ignored. path and url are in the next section, and the keys inside publisher and oauth are in their own sections.

Where the App is servedCopy Anchor Link

path, url or both say where the App's address is. At least one is required.

An administrator can give a different address for one install, either an http or https address or a path that ends in /. That address is kept in the install and the manifest stays as it was.

publisherCopy Anchor Link

oauthCopy Anchor Link

The App signs in through the platform as an OAuth client whose id is the App id. The platform makes that client from the manifest, so a manifest cannot choose a different one: oauth.clientId is not allowed.

redirectPaths become full addresses only when the App's address has a host. When the address is just a path, only redirectUris count. Official Apps ask for ["*"], and the platform does not enforce scopes for an official client.

localesCopy Anchor Link

locales is an object whose keys are languages, such as th. Each value may contain only name, shortName and description, all as text, with shortName up to 12 characters. When the Marketplace is shown in a language that has an entry, those three texts replace the ones above. This is how every official App gives its Thai description.

"locales": {
  "th": { "description": "ตั้งค่าแพลตฟอร์ม รวมถึงบทบาท ผู้ใช้ กลุ่ม OAuth client และคีย์ API" }
}

What the platform does with each field todayCopy Anchor Link

• The Launcher shows shortName (or name) and the App's picture. The picture is an uploaded logo of the App's client when there is one, and otherwise icon.svg under the App's address.
• The Marketplace shows name, description, locales, publisher.name, version, channel, categories, icon and oauth.scopes, and filters by categories.
• screenshots, homepage, support and requires.platform are checked and kept with the install, but no screen shows them and nothing compares requires.platform with the platform yet.

Official AppsCopy Anchor Link

The nine official Apps each ship with a manifest that is built into the platform's image. Every official manifest is checked before it is built in, and one is refused whose manifestVersion is not 1, whose id is repeated or not made of lowercase letters, digits and dashes, whose channel is not official, whose path does not start and end with /, whose shortName is over 12 characters, or whose categories has anything other than maps, data, forms, apps, files or admin.

An official manifest does not carry its own icon. The platform takes the App's icon.svg and keeps it with the built-in manifest as an SVG data URI, and an icon written in the manifest is ignored.