Complete Guide to manifest.webapp Properties
The complete guide to every manifest.webapp
property on KaiOS! This includes many undocumented but useful properties (like userAgentInfo
) as well as properties only intended for system apps. The manifest.webapp
file is a JSON-formatted document that contains important information about your app, including version
, name
, description
, icon
, locales
, and more.
Most importantly, the app manifest contains the list of APIs, permissions, and dependencies that your app needs. It’s analagous to AndroidManifest.xml
for Android apps or Info.plist
for iOS apps.
Aside from manifest.webapp
, KaiOS 2.5 will also accept a packaged app with the file manifest.json
instead (same format, different extension).
manifest.webapp Properties
name
(required)
The human-readable name
for the app. Maximum length is 20 characters (KaiStore) and 8 characters (JioStore).
1{
2 "name": "PodLP"
3}
display
(optional)
Similar to name
, display
if the human-readable name for the app that will be displayed within the Launcher app drawer.
1{
2 "display": "PodLP"
3}
version
(required)
A string that represents the app version
. Format is integers separated by dots.
1{
2 "version": "2.2.1"
3}
Note: format is 3 digits for the KaiStore (i.e. 2.2.1
) and 4 digits for the JioStore (i.e. 2.2.1.0
).
subtitle
(required)
The subtitle that appears below app name in the KaiStore and JioStore. A compelling subtitle increases impressions and installs. Maximum length is 40 characters.
1{
2 "subtitle": "Listen and subscribe to podcast"
3}
description
(required)
The human-readable description that appears on the app detail page in the KaiStore and JioStore. Descriptions should be short and striking.
1{
2 "description": "Discover, listen, and subscribe to podcasts from around the world for free. PodLP is designed specifically for KaiOS to be easy to use both online and offline."
3}
type
(optional)
The app type
that defines access to sensitive device APIs. Must be one of web
, hosted
, privileged
, or certified
. Defaults to web
.
1{
2 "type": "privileged"
3}
launch_path
(optional)
The path within the app’s bundle or origin loaded when the app starts. Defaults to /index.html
.
1{
2 "launch_path": "/index.html"
3}
icons
(required)
An obejct of icon sizes to icon URIs, absolute from the app’s origin. Icons must be square and in .png
format. Icons can be animated PNGs and should have transparent backgrounds. KaiOS recommends a 8-10px transparent border for circle or rounded rectangle shapes with a 30% opacity drop shadow.
1{
2 "icons": {
3 "56": "/img/podlp-logo-56.png",
4 "112": "/img/podlp-logo-112.png"
5 }
6}
Note: 56x56 and 112x112 are required for the KaiStore; an additional 84x84 icon is required for the JioStore.
categories
(required)
Your app’s categories
for placement within the KaiStore.
1{
2 "categories": [
3 "news",
4 "entertainment"
5 ],
6}
Must be one of the following:
social
games
(KaiStore only)utilities
life style
entertainment
health
sports
book/reference
shopping
(KaiStore only)
Note: the JioStore catalogs Games in a separate app, JioGames, while the KaiStore includes a Games tab.
theme_color
(optional)
The app’s theme color, used as the highlight color in the Launcher’s app drawer. Must be in HEX format.
1{
2 "theme_color": "#005665"
3}
Note: this property key is theme
on the JioStore.
developer
(required)
An object identifying the app’s developer, including a human-readable name and URL. Displayed in the app detail page on the KaiStore.
1{
2 "developer": {
3 "name": "PodLP",
4 "url": "https://podlp.com"
5 },
6}
cursor
(optional)
A boolean that enables the emulated cursor similar to the Browser app.
1{
2 "cursor": false,
3}
Note: for the best user experience,
don’t use the emulated cursor. Instead, use D-Pad navigation (ArrowUp
, ArrowDown
, ArrowLeft
, ArrowRight
) to change focus, similar to accessible web navigation.
fullscreen
(optional)
A boolean that determines whether to launch the app in full-screen mode (hides the 26px
-tall system status bar).
1{
2 "fullscreen": false,
3}
origin
(optional)
The origin
field determines your app’s location.origin
at runtime. The origin
value must start with the app:
protocol and you must be the owner of the specified domain name. Defaults to an auto-generated UUID, i.e. app://ff0a7f9f-8911-445b-a08c-d111a3347a4f
.
1{
2 "origin": "app://podlp.com",
3}
Note: only applies to privileged
and certified
packaged apps.
userAgentInfo
(optional)
Appends a string to the end of the User-Agent
header went with most requests, including XMLHTTPRequest, media elements (i.e. img
, audio
, and video
), as well as document navigation.
1{
2 "userAgentInfo": "PodLP/2.2.1",
3}
Note: you can only append to the device User-Agent
, you cannot replace it. User-Agent
was considered a
forbidden header that cannot be set in XMLHTTPRequest or Fetch on KaiOS.
chrome
(optional)
Paired with "fullscreen": true
, and "background_color": "transparent"
, this property sizes your app to 100% height (320x240) with the system status bar displayed on top of your app. Useful for apps that have image backgrouns but don’t want to hide the system status bar. Only valid property and value pair is "statusbar": "overlap"
; defaults to non-overlapping.
1{
2 "fullscreen": true,
3 "background_color": "transparent",
4 "chrome": {
5 "statusbar": "overlap"
6 },
7}
Note: this value is ignored if the app is not fullscreen
.
permissions
(optional)
The list of permissions
that your app requests. Must correspond to the appropriate level based on app type
, or permissions will be rejected. Check out the
complete list of KaiOS permissions for information on available permissions and security levels.
1{
2 "permissions": {
3 "audio-channel-content": {
4 "description": "To play podcast audio files in the background."
5 },
6 },
7}
priority
(optional)
Sets the mozapptype
to hipri
on the app’s iframe
. Default is null, and only allowed value is "high"
. Only applies to privileged
and certified
packaged apps.
Warning: This property is intended for important apps that receive urgent messages or calls (i.e. WhatsApp). Setting it does not guarantee your app will not be terminated due to memory pressure.
1{
2 "priority": "high",
3}
This property adjusts several properties in the Hardware Abstraction Layer (HAL), resulting in terminating preallocated process before the priority foreground app to maintain memory for memory-sensitive apps.
FYI: once an app is no longer visible, it’s in the background and can be marked for termination. The grace period is 1 second by default, or 5 seconds if the app is “perceivable,” like playing music on the "content"
audio channel (see Pref dom.ipc.processPriorityManager.backgroundPerceivableGracePeriodMS
).
messages
(optional)
A list of System Messages that your app responds to. Many system messages require special permissions that are for certified
apps only. See
SystemMessagePermissionsChecker.jsm for the list of permissions.
1{
2 "messages": [
3 { "serviceworker-notification": "/index.html" }
4 ],
5}
The following is a list of useful System Messages on KaiOS 2.5:
audiochannel-interruption-begin
audiochannel-interruption-ended
media-button
headset-button
activity
alarm
(requiresalarms
permission)serviceworker-notification
(requiresdesktop-notification
permission)notification
(requiresdesktop-notification
permission)push
(requirespush
permission)push-register
(requirespush
permission)
redirects
(optional)
Internal URLs your app uses to handle external processes. Common example includes OAuth authentication.
1{
2 "redirects": [{
3 "from": "http://facebook.com/authentication/success.html",
4 "to": "/app/main_interface.html"
5 }]
6}
Note: only applies to privileged
and certified
apps.
activities
(optional)
A list of Web Activities that your app will respond to, with optional filters. This includes common activities for viewing and sharing content, as well as custom activities for your app.
1{
2 "activities": {
3 "share": {
4 "href": "/index.html",
5 "disposition": "window",
6 "filters": {
7 "type": "url",
8 "url": {
9 "required": true,
10 "regexp": "https?:.{1,2048}"
11 }
12 }
13 }
14 },
15}
Common activities include:
view
share
pick
browse
open
For more examples and details, see the article on KaiOS Web Activities.
locales
(optional)
An object of locales
for translating the app’s name
, subtitle
, and description
. Keys are language tags defined in (RFC 4646).
1{
2 "locales": {
3 "en-US": {
4 "name": "PodLP",
5 "subtitle": "Listen, download, and subscribe to podcasts",
6 "description": "Discover, listen, and subscribe to podcasts from around the world for free. PodLP is designed specifically for KaiOS to be easy to use both online and offline."
7 }
8 },
9}
default_locale
(optional)
The default locale for the app. Must match one set in localed
.
1{
2 "default_locale": "en-US",
3}
orientation
(optional)
Supported orientations for the app. Can be an array or a single value.
1{
2 "orientation": [
3 "portrait-primary",
4 "landscape-primary"
5 ],
6 "orientation": "default",
7}
Must be one or more of the following:
portrait
landscape
portrait-primary
landscape-primary
portrait-secondary
landscape-secondary
Note: there is only two devices in the landscape orientation (320x230), the popular JioPhone 2 and the Xandos X5.
role
(optional)
If set, must be one of system
, homescreen
, theme
, addon
, or langpack
. Only certified apps can be theme
s and only privileged or certified apps can be addon
s.
1{
2 "role": "system",
3}
Note: this is only intened for pre-installed certified
apps, not third-party apps.
datastores-access
(optional)
Data stored accessed using the Data Store API.
1{
2 "datastores-access": {
3 "download_store": {
4 "readonly": false,
5 "description": "Stores download finished"
6 }
7 },
8}
Note: only applies to certified
apps.
datastores-owned
(optional)
Data stored owned by this app, exposed via the Data Store API.
1{
2 "datastores-owned": {
3 "silent-apps": {
4 "access": "readwrite",
5 "description": "Silent install app list"
6 }
7 },
8}
Note: only applies to certified
apps.
csp
(optional)
The Content Security Policy (CSP) for the app.
1{
2 "csp": "default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'",
3}
The default policies applied on KaiOS are:
Privileged
1default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'
Certified
1default-src *; script-src 'self'; object-src 'none'; style-src 'self'
Note: defaults CSPs cannot be overridden, only added to (more restrictive).
appcache_path
(optional)
Location of an Application Cache manifest file.
1{
2 "appcache_path": "/cache.manifest",
3}
Note: appcache_path
only applies to hosted
app types.
dependencies
(optional)
Specify required dependencies
which, if missing, will prevent installation. Recommended when using the
KaiAds SDK.
1{
2 "dependencies": {
3 "ads-sdk": "1.5.8"
4 },
5}
Note: dependencies
only applies to privileged
or certified
apps.
widgetPages
(optional)
The
Widget API allows privileged
apps to embed other applications in their own iframe, e.g. homescreen, lockscreen, etc. widgetPages
exposes widgets and apps embedding widgets require the
"embed-widgets"
permission.
1{
2 "widgetPages": [
3 "/widget.html"
4 ],
5}
Warning: The Widgets API was never finalized and is disabled by default in nsGenericHTMLFrameElement.cpp.
background_color
(optional)
The app background color, used to influence the system status bar theme (light or dark). System status bar theme can also be controlled dynamically using the meta tag in the page <head>
, i.e. <meta name="theme-color" content="rgb(255, 255, 255)" />
.
1{
2 "background_color": "transparent",
3}
deeplinks
(optional)
Register deep links that will trigger a Web Activity, also registered in your app’s manifest, using the value in "action"
(i.e. "open-deeplink"
).
1{
2 "deeplinks": {
3 "regex": "^(app://)(kaios-store|kaios-plus)(.kaiostech.com)($|/$|/\\?(apps|postResult)=)",
4 "action": "open-deeplink"
5 },
6}
Note: available on KaiOS 3.0 and select sub-versions of KaiOS 2.5.
connections
(optional)
Register for system Inter-App Communications (IAC).
1{
2 "connections": {
3 "kaipay-to-kaistore": {
4 "description": "Communication with KaiPay",
5 "rules": { }
6 }
7 },
8}
Note: only intended for pre-installed certified
apps.
receipts
(optional)
Up to 1 MiB, format is JWT + “~” + JWT.
1{
2 "receipts": [
3 ""
4 ]
5}
precompile
(optional)
An array of script URIs containing “asm.js” to compile at install time off the main thread. KaiOS 2.5 only, since KaiOS 3.0 supports WASM. Compilation makes installation time longer, but reduces the time to start the app.
1{
2 "precompile": [
3 "game.js",
4 "database.js"
5 ]
6}
entry_points
(optional)
An object of entry points into the app. Let’s you define sub-apps that will also show in the default Launcher’s app drawer.
1{
2 "entry_points": {
3 "lsk": {
4 "launch_path": "/index.html?entry=rupee&localentry=rupee",
5 "name": "JioPay",
6 "locales": {
7 "en-US": {
8 "name": "JioPay",
9 "description": "Use JioPay to make payment securely from Jiophone"
10 }
11 }
12 }
13 },
14}
manifest.webmanifest
on KaiOS 3.0
KaiOS 3.0 changed the manifest structure to align with the standard Web Manifest format. Instead of a single manifest.webapp
file for every locale, KaiOS 3.0 requires one manifest.webmanifest
(i.e. manifest.en-US.webmanifest
) file for each locale. Most proprties are the same, but they have been moved to the proprietary b2g_features
section.
Here’s a short example from my Bing Wallpaper app.
1{
2 "id": "bingv3",
3 "name": "Bing Wallpaper",
4 "description": "Beautiful wallpapers from Bing, available daily. Not affiliated with nor endorsed by Microsoft Corporation.",
5 "display": "standalone",
6 "theme_color": "#00897b",
7 "lang": "en-US",
8 "start_url": "/index.html",
9 "icons": [
10 {
11 "src": "/logo_56.png",
12 "type": "image/png",
13 "sizes": "56x56"
14 },
15 {
16 "src": "/logo_112.png",
17 "type": "image/png",
18 "sizes": "112x112"
19 }
20 ],
21 "b2g_features": {
22 "display": "Bing Wallpaper",
23 "version": "3.0.0",
24 "subtitle": "Beautiful wallpapers daily",
25 "type": "web",
26 "categories": [
27 "utilities"
28 ],
29 "developer": {
30 "name": "Last Byte LLC",
31 "url": "https://kaios.dev/"
32 },
33 "cursor": false,
34 "fullscreen": true,
35 "chrome": {
36 "statusbar": "overlap"
37 }
38 }
39}
Note: the only non-standard property in the manifest root is id
. It’s required to uniquely identify your app and is often just the lowercase version of your app name.
Conclusion
As you can see, a lot more than just app name and icons go into KaiOS’ manifest.webapp
file. The app’s manifest is what enables it to access certain APIs, interact with the system for tighter integration, and enables the best possible user experience.
For more examples, see the KaiOS Manifest documentation. If you’re confused about specific manifest properties and need an experienced partner for KaiOS development, contact the author from the About page.