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:
socialgames(KaiStore only)utilitieslife styleentertainmenthealthsportsbook/referenceshopping(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-beginaudiochannel-interruption-endedmedia-buttonheadset-buttonactivityalarm(requiresalarmspermission)serviceworker-notification(requiresdesktop-notificationpermission)notification(requiresdesktop-notificationpermission)push(requirespushpermission)push-register(requirespushpermission)
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:
viewsharepickbrowseopen
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:
portraitlandscapeportrait-primarylandscape-primaryportrait-secondarylandscape-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 themes and only privileged or certified apps can be addons.
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.