An Esper web app is an Android web application that users can upload to their Esper tenants. You might use this service rather than a traditional app or Google Web App if the website you want to base it on uses HTTP. Esper web apps also allow you to customize the app with managed configurations.
In this article:
Getting Started
To get started, copy your Esper enterprise ID and API key. We recommend using a dedicated account to generate the API key.
Then, create a support ticket to request access to the Esper Web App site. On the site, you will be asked to fill out a form. The form will ask questions about customizing the application. See the Customization section of this article for more information.
User Permissions
On the device, the user will be requested to accept the following permissions:
- Camera: For web pages that may make use of the device's camera (e.g., QR-code scanning, etc.). You may need to set the device's Camera App to the SHOW state in the device details section.
- Location: For web pages that may use the device's location (e.g., maps, etc.).
- Microphone: For web pages that may use the device's microphone.
- Storage: For uploading or saving files to the device (if allowed).
These permissions may be changed at any time via a Template, Blueprint, API, etc.
Customization
When you complete the form, you’ll be asked to provide details about the app’s displays and operations in addition to your Esper enterprise ID and API key.
Name
Enter an app name that will appear on the device and in the Epser tenant.
Target URL
Enter the URL of the website for the web app.
Icon
Upload a 512 x 512 px PNG file.
Default
In default mode, the app will show a status bar, the app title, a web page, and a navigation bar.
Minimal
In minimal mode, the app will show the status bar, web page, and navigation bar.
Fullscreen
In fullscreen mode, the app will show the web page. The system bars are hidden by default but can be revealed with gestures.
Clear App Data
Once the app is moved to the background, all user data will be cleared. Use this option if the app is intended for one-time use by customers. For example, a check-in app in a healthcare setting.
Open a New Window in the Current View
By default, the app will only open links in the current window and not in a new tab or window. Set this setting to true to allow links to open in a new window.
Show Toasts
A toast is a temporary error or warning message that sometimes appears.
- Error: A red box with white text will appear.
- Warning: An orange box with black text will appear.
HTTP Allow Domains
By default, Esper web apps will not load domains beginning with http.
You can allow multiple http domains by entering the web addresses in a comma-separated list. There is also an option to allow all HTTP domains.
Managed Configurations
Esper web apps allow you to manage many types of app configurations. Use the Esper console to apply managed configurations after installing the Esper web app on the device.
Description | Key | Value | Default Value | Notes |
Allow Android Settings | allowAndroidSettings | Boolean (e.g. true or false) | TRUE | Allow the user to access Android Wifi Settings via the shortcut, if Esper Settings is not present |
Allow Cookies | allowCookie | Boolean (e.g. true or false) | TRUE | |
Allow DOM Storage | allowDomStorage | Boolean (e.g. true or false) | TRUE | |
Allow Download On Mobile Data | allowDownloadOnMobileData | Boolean (e.g. true or false) | FALSE | |
Allow Download Over Metered | allowDownloadOverMetered | Boolean (e.g. true or false) | TRUE | |
Allow Download Over Roaming | allowDownloadOverRoaming | Boolean (e.g. true or false) | TRUE | |
Allow Downloads | allowDownloads | Boolean (e.g. true or false) | FALSE | |
Allow File Access | allowFileAccess | Boolean (e.g. true or false) | FALSE | |
Allow File Preview | allowDownloadedFilePreview | Boolean (e.g. true or false) | TRUE | |
Allow Geolocation | allowGeolocation | Boolean (e.g. true or false) | false below 1.1007; True for 1.1007+ | |
Allow Javascript | allowJavascript | Boolean (e.g. true or false) | TRUE | |
Allow Open New Windows In Current View | allowOpenNewWindowsInCurrentView | Boolean (e.g. true or false) | TRUE | |
Allow Plugins | allowPlugins | Boolean (e.g. true or false) | FALSE | |
Allow Redirect File Preview | allowRedirectFilePreview | Boolean (e.g. true or false) | FALSE | |
Allow Settings | allowSettings | Boolean (e.g. true or false) | TRUE | Allow the user to access any Settings by any method (e.g. shortcut, menu, etc.) |
Allow Settings Shortcut | allowSettingsShortcut | Boolean (e.g. true or false) | TRUE | Allow the user to access Esper Settings, if present, or Android Wifi Settings via the shortcut |
Allow Swipe Navigation | allowSwipeNavigation | Boolean (e.g. true or false) | TRUE | |
Allow Swipe Refresh | allowSwipeRefresh | Boolean (e.g. true or false) | TRUE | |
Allow Zoom Controls | allowZoomControls | Boolean (e.g. true or false) | FALSE | Pinch out to magnify view and Pinch in to reduce view. Requires setSupportZoom to be true. |
Auto Deny Geolocation | autoDenyGeolocationPermission | Boolean (e.g. true or false) | FALSE | Auto denies permission when visiting the page. Requires allowGeolocation to be true. |
Auto Grant Geolocation | autoGrantGeolocationPermission | Boolean (e.g. true or false) | FALSE | Auto grants permission when visiting the page. Requires allowGeolocation to be true. |
Block Network Image | blockNetworkImage | Boolean (e.g. true or false) | FALSE | |
Block Network Loads | blockNetworkLoads | Boolean (e.g. true or false) | FALSE | |
Clear Data on Focus Loss | clearDataOnFocusLoss | Boolean (e.g. true or false) | FALSE | |
Hide App Title Bar | hideAppTitleBar | Boolean (e.g. true or false) | NOT supported for apps with Fullscreen mode by default. | |
Javascript can Open Windows Automatically | javaScriptCanOpenWindowsAutomatically | Boolean (e.g. true or false) | FALSE | |
Load Images Automatically | loadsImagesAutomatically | Boolean (e.g. true or false) | TRUE | |
Load with Overview Mode | loadWithOverviewMode | Boolean (e.g. true or false) | TRUE | |
Override Key Event | overrideKeyEvent | Boolean (e.g. true or false) | FALSE | false will disable external keyboards |
Retain Geolocation Permission | retainGeolocationPermission | Boolean (e.g. true or false) | FALSE | Keep permission when revisiting the page. Requires allowGeolocation to be true. |
Set Action Bar Background Color | setActionBarBackgroundColor | String | "#FF3700B3" | |
Set Action Bar Text Color | setActionBarTextColor | String | "White" | |
Set App Title | setAppTitle | String | Defined on App Creation | NOT supported for apps with Fullscreen mode by default. |
Set Cache Mode | setCacheMode | String (e.g., "LOAD_DEFAULT", "LOAD_CACHE_ELSE_NETWORK", "LOAD_CACHE_ONLY", "LOAD_NO_CACHE") | LOAD_NO_CACHE for 1.1002, LOAD_DEFAULT for 1.1003+ | |
Set Database Enabled | setDatabaseEnabled | Boolean (e.g. true or false) | TRUE | |
Set Default Web URL | webappURL | String (e.g., "https://www.esper.io") | Defined on App Creation | |
Set Display Zoom Controls | setDisplayZoomControls | Boolean (e.g. true or false) | FALSE | Displays when view magnification is detected. Requires allowZoomControls and setSupportZoom to be true. |
Set Initial Scale | initialScale | Int | 0 | |
Set Layer Type | setLayerType | String ("NONE", "SOFTWARE", "HARDWARE") | "HARDWARE" for 1.1002, "NONE" for 1.1003+ | |
Set Media Playback Requires User Gesture | setMediaPlaybackRequiresUserGesture | Boolean (e.g. true or false) | true for 1.1002, false for 1.1003+ | |
Set Mixed Content Mode | setMixedContentMode | String ("COMPATIBILITY", "ALWAYS", "NEVER") | "NEVER" | |
Set Progress Bar Background Color | setProgressBarBgColor | String | "Black" | |
Set Progress Bar Color | setProgressBarColor | String | "#FFBB86FC" | |
Set Support Zoom | setSupportZoom | Boolean (e.g. true or false) | FALSE | |
Set User Agent String | setUserAgentString | String | "Esper Web App" (> 1.1004)/ Android User Agent | |
Settings Shortcut Threshold | settingsShortcutThreshold | Integer | 4 | How many times the user will need to swipe at the bottom of the page to show settings. |
Show Back Button | showBackBtn | Boolean (e.g. true or false) | TRUE | |
Show Error Toasts | showErrorToasts | Boolean (e.g. true or false) | TRUE | |
Show Forward Button | showFwdBtn | Boolean (e.g. true or false) | TRUE | |
Show Home Button | showHomeBtn | Boolean (e.g. true or false) | TRUE | |
Show Menu Icons | showMenuIcons | Boolean (e.g. true or false) | TRUE | |
Show Progress Bar | showProgressBar | Boolean (e.g. true or false) | TRUE | |
Show Warning Toasts | showWarningToasts | Boolean (e.g. true or false) | TRUE | |
Show Warning Toasts | showWarningToasts | Boolean (e.g. true or false) | TRUE | |
Toggle Safe Browsing | toggleSafeBrowsing | Boolean (e.g. true or false) | TRUE | For Android 8.0 and above. |
URL Allow List | UrlAllowList | String Array | To create a list of URLs, see the Allowing and Blocking URLs section. | |
URL Block List | UrlBlockList | String Array | To create a list of URLs, see the Allowing and Blocking URLs section. | |
Use Wide View Port | useWideViewPort | Boolean (e.g. true or false) | TRUE |
Allowing and Blocking URLs
Expected Behavior
Let's go over some of the expected behavior for the app if allowed or blocked URLs are used. Keep in mind, this behavior may be exclusive to web apps. See Blocking URLs with JSON to learn how to use block lists for other types of apps.
List Entries
- The wildcard character ("*") will try to match any character or sequence of characters up to that point if included in the entry
- Protocols (e.g. HTTP & HTTPS) will be ignored
- Blank entries will be ignored
- Entries will be trimmed of excess whitespace
URL Checking Process
- Protocols (e.g. HTTP & HTTPS) will be ignored
- If the wildcard is present in the Allow list then any site will be accessible
- If the wildcard is present in the Block list all sites, except those in the Allow list, will be blocked
- The loading site will first be compared to the Block list if that list has a standalone wildcard entry or if not explicitly blocked before being compared to the rest of the Blocked entries
- If the site is not blocked (either by an explicit entry or via wildcard) or explicitly stated in the Allow list, then the site will be allowed to load
- The crafting of your lists may require some tweaking and experimentation as your live service changes to ensure the behavior you want.
In the following examples, we break down the differences between the allow and block lists and how to use wildcards ('*') to indicate additional characters in a URL.
Basic Example
Let's say that the user has defined the following for their lists:
{ "UrlBlockList": [ "twitter.com", "en.wikipedia.org*", ], "UrlAllowList":[ "en.wikipedia.org/wiki/Esper" ] }
If the device user attempts to navigate to "twitter.com", then the attempt will be blocked. However, if they attempt to navigate to "twitter.com/esper" then the attempt will be allowed, since it is not explicitly blocked and no entries within the block list with wildcards match the URL.
If the user tries to access any English Wikipedia page, except the Esper Wiki page, they will be blocked. However, if the user tries to access any other language variant or even the mobile variant of a Wiki page then the site will be allowed to load.
Generic Wildcard Example
Let's take the following list:
{ "UrlBlockList": [ "*" ], "UrlAllowList": [ "mysite.com*" ] }
In this case, if the device user tries to access any site that is not a subdomain of “mysite”, the attempt will be blocked.
However, this could mean that third-party services that might be used by the site, for example, an SSO login service, may be blocked and will need to be allowed to get the expected behavior.
In some cases, the site may try to redirect you to a different subdomain. For example, a mobile variant (e.g. “m.mysite.com” or “about.mysite.com”). With the rule defined above both of these domains will be blocked.