Installable Apps

Open in ChatGPT

24.21

Java API

The @AppProfile annotation in webforJ enables you to make your app installable on supported platforms. Installable web apps integrate with the device's operating system. When installed, they appear on the home screen or app menu, similar to native apps. To achieve this, certain metadata such as name, description, and icons must be provided. These details help the operating system identify and display the app.

Secure Origin Requirement

For an app to be installable, it must be served from a secure origin, such as https. Browsers reject installation attempts on insecure origins. However, this rule doesn't apply when serving the app locally from localhost during development.

For more details about secure contexts and their importance, refer to the Secure Contexts MDN documentation.

Browser support

Support for installing a web app varies by browser and by platform.

Desktop

• Chromium browsers (Chrome, Edge, Opera, Brave, and others) install any app that ships a manifest file on all supported desktop operating systems.
• Safari supports File → Add to Dock on macOS Sonoma (Safari 17) and later. The flow works for any web app, with or without a manifest file.
• Firefox doesn't support installing web apps from a manifest file on desktop.

Mobile

• On Android, Chrome, Edge, Firefox, Opera, and Samsung Internet all support installing web apps.
• On iOS 16.3 and earlier, web apps can be installed only from Safari (Share → Add to Home Screen).
• On iOS 16.4 and later, web apps can be installed from the Share menu in Safari, Chrome, Edge, Firefox, and Orion.

@AppProfile annotation

The @AppProfile annotation is applied to the main app class and requires minimal configuration. At a minimum, you need to provide:

• name: The full name of the app.
• shortName: A concise version of the name for use in limited-space contexts.

Additional optional properties allow customization of the app's appearance and behavior.

When the @AppProfile annotation is present, webforJ:

• Automatically sets up necessary meta tags.
• Generates a Web Application Manifest.
• Serves related resources such as icons and screenshots.

Example: Applying @AppProfile

@AppProfile(
  name = "Zyntric Bank",
  shortName = "ZBank",
  description = "Zyntric Bank is a simple banking application built with webforJ",
  screenshots = {
    @AppProfile.Screenshot(
      src = "ws://img/screenshots/s1.jpg",
      sizes = "1080x1920"
    )
  }
)
public class Application extends App {
}

@AppProfile properties

The following table lists all properties supported by the @AppProfile annotation:

Property	Type	Description	Default Value
name	String	The full name of the app, displayed in app menus and installation dialogs.	Mandatory
shortName	String	A short version of the name, used in contexts with limited space. Shouldn't exceed 12 characters.	Mandatory
description	String	A brief description of the app, displayed during installation and in app settings.	""
themeColor	String	The theme color for the app, applied to the browser UI when the app is launched.	"#ffffff"
backgroundColor	String	The initial background color for the app during loading.	"#f8fafc"
startUrl	String	The URL to open when the app is launched.	"."
display	Display Enum	The display mode of the app (e.g., FULLSCREEN, STANDALONE, BROWSER).	STANDALONE
orientation	Orientation Enum	The default orientation of the app (e.g., PORTRAIT, LANDSCAPE, NATURAL).	NATURAL
icons	Icon[]	An array of icons representing the app at different resolutions.	[]
defaultIcon	DefaultIcon	Specifies a default icon for the app. Automatically generates icon paths in multiple sizes if configured.	icons://icon.png
screenshots	Screenshot[]	An array of screenshots for the app, used in installation dialogs.	[]
categories	String[]	Categories to classify the app (e.g., Finance, Shopping).	[]

@AppProfile.Icon properties

Icons define the visual representation of your app in menus and home screens. The @AppProfile.Icon annotation supports the following properties:

Property	Type	Description	Default Value
src	String	The path to the icon. This can be an absolute URL, or a ws:// path.	Mandatory
sizes	String	A string that specifies one or more sizes of the image in the format WidthxHeight (e.g., 512x512).	Mandatory
type	String	The media type of the icon (e.g., image/png, image/jpeg). If not provided then it will be detected	""
purpose	String	The purpose of the icon (e.g., any, maskable, monochrome).	""

Example

@AppProfile.Icon(
  src = "ws://icons/icon-512x512.png",
  sizes = "512x512",
  type = "image/png"
)

@AppProfile.DefaultIcon properties

The DefaultIcon annotation simplifies the configuration of app icons by generating multiple size variants from a base icon. It produces icons at the resolutions devices commonly request.

Property	Type	Description	Default Value
value	String	The path to the base icon file. This can be an absolute URL, or a ws:// path.	Mandatory
sizes	int[]	An array of sizes to generate, specified as integers (e.g., {144, 192, 512}).	{144, 192, 512}

Icon File Requirements

This configuration doesn't generate the actual icon files for the app automatically. Instead, it uses the @AppProfile.DefaultIcon annotation to generate corresponding @AppProfile.Icon entries for each specified size.

If using the webserver protocol

• You must provide a base icon.png file in the static/icons folder.
• You are expected to include additional icon variations named icon-144x144.png, icon-192x192.png, and icon-512x512.png.
• These specific sizes cover the resolutions devices commonly request.

If using the icons protocol

• You are expected to provide a base icon.png file in the /icons folder.
• The icons endpoint dynamically provides different icon sizes on demand when they're requested.

@AppProfile.Screenshot properties

Screenshots provide a preview of the app in installation dialogs or app stores. The @AppProfile.Screenshot annotation supports the following properties:

Property	Type	Description	Default Value
src	String	The path to the screenshot. This can be an absolute URL, or a ws:// path.	Mandatory
sizes	String	A string that specifies one or more sizes of the image in the format WidthxHeight (e.g., 1080x1920).	Mandatory
type	String	The media type of the screenshot (e.g., image/png, image/jpeg). If not provided then it will be detected	""
label	String	A descriptive label for the screenshot.	""
formFactor	String	The form factor of the screenshot (e.g., narrow, wide).	""
platform	String	The platform for which the screenshot is intended (e.g., ios, android).	""

Example

@AppProfile.Screenshot(
  src = "ws://img/screenshots/s1.jpg",
  sizes = "1080x1920"
)