Traditional HTML5 technology is sensitive to network conditions, which can degrade the performance of HTML5 pages. Offline packages address this issue while preserving the benefits of HTML5.
An offline package is a compressed file that bundles static resources, such as HTML, JavaScript, and CSS files. You can download the offline package to a local device in advance. When the client opens the package, it loads the resources directly from the local device, minimizing the impact of network conditions on HTML5 pages.
Using HTML5 offline packages provides the following advantages:
Improve user experience: Embed static resources in your application and release it. When users first open the application, they do not need to download these resources over the network and can start using the application immediately.
Enable dynamic updates: When you release a new version or an emergency fix, place the modified resources into an offline package. By updating the configuration, the application automatically downloads the update. This allows users to receive updates sooner because you do not need to go through an app store review process.
How offline packages work
This section explains how offline packages work, including the following topics:
Offline package structure
An offline package is a compressed file in .amr format. If you change the .amr extension to .zip and decompress the file, you can see that it contains HTML resources and JavaScript code. After the HTML5 container loads these resources, they can be rendered in a WebView.
For example, the following figure shows the folder structure of a typical resource plan on an iOS system:
First-level folder: Represents the ID of a general resource plan, such as
20150901.The second-level folder and its subdirectories contain custom resource files. Save all frontend files in a single folder. You can give the folder a custom name, such as
/www. Also, set the main entry file that the offline package opens by default, such as/www/index.html.
Offline package types
During HTML5 development, you often use basic common libraries, such as Zepto and FastClick. In an app's WebView, the cache can be unreliable. On some device models, the cache is automatically cleared after the app is closed. To further improve the performance of HTML5 pages, use a global offline package. A global offline package bundles a series of common resources into a special app package and sends it to the client.
Offline packages are divided into the following types:
Global offline package: Contains public resources that multiple applications can share.
Private offline package: Can only be used by a single application.
When you use a global offline package, the system tries to read from this package whenever it accesses an HTML5 page. If the package contains the requested resource, the system retrieves it directly from the package instead of from the network. Therefore, the main purpose of the global offline package mechanism is to manage the use of common libraries.
To ensure wide client coverage and versatility, this package is typically updated at least once a month. The size of the offline package is also strictly controlled.
Rendering process
When an HTML5 container requests a resource, it uses the same URL to access both local and online resources.
The HTML5 container intercepts the request first. After the request is intercepted, one of the following occurs:
If a local resource can fulfill the request, the HTML5 container uses the local resource.
If no local resource can fulfill the request, the HTML5 container uses an online resource.
Therefore, the WebView is not aware of whether the resource is local or online.
The download of an offline package depends on its configuration:
If Download Timing is set to Wi-Fi only, the offline package is automatically downloaded in the background only on a Wi-Fi network.
If Download Timing is set to Download over all networks, the offline package is automatically downloaded over non-Wi-Fi networks, which consumes user data. Use this option with caution.
If a user opens the app before the offline package finishes downloading, the app redirects to a fallback address to display the online page. The fallback feature handles cases where the offline package has not finished downloading. When an offline package is published, a corresponding online version is also published to a CDN. The folder structure of the online version is the same as the offline package. The fallback address is sent to the local device along with the offline package information. In cases where the offline package has not finished downloading, the client intercepts the page request and redirects it to the corresponding CDN address. This allows the app to switch between online and offline pages at any time.
Offline package running mode
To open an offline package, complete the following steps:
Request package information. The client requests offline package information from the server and stores it in a local database. The offline package information includes the download address and version number of the package.
Download the offline package. The client downloads the offline package from the server to the mobile phone.
Install the offline package. The client copies the package from the download folder to the installation folder on the phone.
Virtual domain names
Virtual domain names are a unique container mechanism that works only for offline applications. After a page is saved on the client, the WebView uses the file scheme to access it from the local device. However, the user can then see the file path in the address bar. This causes the following problems:
User experience. When users see a file address, they may feel that the exposed address is insecure or unfamiliar.
Security. The file protocol directly includes the local path. This means any user can see the file path, which creates a security risk.
For these reasons, use the virtual domain name mechanism instead of directly using a file path for access. A virtual domain name is an HTTPS domain address that complies with the URL scheme specification, such as https://xxxxxxx.HTML5app.example.com. The parent domain of the virtual domain name, such as example.com, must be a domain name that you registered.
The standard format for a virtual domain name is as follows:
https://{appid}.HTML5app.example.com.