How to transform an HTML 5 mobile app into an HTML 5 mini program

This topic describes the process to transform an HTML5 mobile app (native app) into an HTML5 mini program. With the web development approach, Progressive Web Application (PWA), this transformation makes it possible to have a scalable solution while keeping the digital experience consistent.

The following two types of mini programs are supported on Mini Program Platform:

  • Mini Program based on DSL (Domain Specific Language)

We recommend that you develop the default DSL-based mini programs. For more information, see About Mini Program.

  • Mini Program based on HTML5

However, to help you integrate your existing HTML5 mobile apps with the wallet app, you can choose the HTML5 mini program type.

What are HTML5 mini programs?

HTML5 mini programs are the mini programs that are transformed from HTML5 mobile apps. HTML5 mini programs run in the WebView environment, so you can develop HTML5 mini programs as you do for web pages. Compared with HTML5 mobile apps, HTML5 mini programs are powered with more capabilities by calling mini program JSAPIs, thus improving user experience.

Benefits

There is no need to start from scratch if you already have an existing HTML5 mobile app. Different roles can enjoy the following benefits by transforming your HTML5 app into a mini program:

  • Convenient

As compared with the time-consuming learning of the Mini Program framework, developers can reuse their familiar web development knowledge to get started with Mini Program.

  • Cost-efficient

Merchants, ISVs, and wallet developers just need to add a few lines of JavaScript code to the existing HTML5 app, and the HTML5 mini programs become ready.

  • Consistent and user-friendly

End users can also benefit from a consistent user experience of mini programs and native apps.

Before you start

Before you start, make sure you have applied for an account and get on-boarded.

Also, you can see the following process flow to get an overview of the detailed steps:

image.png

Note:

As compared with the steps of DSL mini programs, the following steps that are shown in red in the above process flow are required:

  • HTML5 mini program type
  • Entrance URL

Entrance of the HTML5 mini program. You can modify the entrance URL after the HTML5 mini program is created.

The following steps that are shown in gray in the above process flow are optional:

  • IDE

You can develop the HTML5 mini programs just like you develop HTML5 web pages.

  • Build package process
  • Quality review

See procedures for a step-by-step guide on how to transform an HTML5 mobile app (native app) into an HTML5 mini program.

Procedures

To transform HTML5 apps to mini programs, complete the following steps:

Step 1: Create the HTML 5 mini program

When you create a new mini program, choose Mini Program Based on HTML5 and enter the URL of your HTML5 mobile app into the Entrance URL field.

image

For more information on creating mini programs, see Create Mini Programs.

Step 2: Use wallet capabilities

To use the mini program JSAPIs, integrate the SDK according to your business requirements.

a. Mini Program JSAPIs in HTML5

Follow the steps below to use mini program JSAPIs in HTML5:

  1. Import the JSBridge SDK by importing the following JS file to the HTML file:
copy
<script src="https://cdn.marmot-cloud.com/npm/hylid-bridge/2.10.0/index.js"></script>

See the following HTML sample codes for reference:

copy
<!DOCTYPE html>
<html>
<head>
  <title>Miniprogram JSAPI Demo</title>
  <script src="https://cdn.marmot-cloud.com/npm/hylid-bridge/2.10.0/index.js"></script>
</head>
<body>
  <div>
    <button id="alert">my.alert</button>
  </div>
  <script>
    var alertButton = document.getElementById('alert');
    alertButton.addEventListener('click', function () {
      my.alert({
        title: 'Test Alert!!',
        content: window.navigator.userAgent,
        buttonText: 'Alert Button',
        success: function (res) {
          my.alert({
            content: 'success!' + JSON.stringify(res),
          });
        },
        fail: function () {
          my.alert({
            content: 'fail!',
          });
        },
        complete: function () {
          my.alert({
            content: 'complete!',
          });
        },
      });
    });
  </script>
</body>
</html>
  1. Call an API from the following available API list. The parameter in the API is an object. Each API has the following properties:
    • success: callback function that indicates the successful API calling.
    • fail: callback function that indicates the failed API calling.
    • complete: callback function that indicates the completed API calling.

Take the my.alert JSAPI as an example. In this API, success, fail, and complete are the common properties. Specific properties are title, content, and buttonText.

For example, see the following sample codes to know how the IAlertOptions interface can be defined:

copy
interface IAlertOptions {
  title?: string;
  content?: string;
  buttonText?: string;
  success?: () => void;
  fail?: () => void;
  complete?: () => void;
}

Available API list

The following table lists all available JSAPIs. You can apply for your own JSAPIs if required.

JSAPI Name

Description

my.alert

Displays alert box.

my.confirm

Displays confirmation box.

my.prompt

Prompts a user input

my.showToast

Displays a toast, which disappears within certain seconds.

my.hideToast

Hides a toast.

my.showLoading

Displays the loading message.

my.hideLoading

Hides the loading message.

my.setNavigationBar

Sets the navigation bar text and style.

my.showNavigationBarLoading

Shows navigation bar loading.

my.hideNavigationBarLoading

Hides navigation bar loading.

my.request

Network request

my.getSystemInfo

Gets system information.

my.getNetworkType

Gets current network status.

my.showAuthGuide

Guides users to grant the authorization when the permission is needed.

my.getAuthCode

Gets user's authorization code.

my.saveImage

Saves online images to cellphone album.

my.chooseImage

Takes a photo or chooses a photo from the album on the phone.

my.previewImage

Previews images.

my.getImageInfo

Gets image information.

my.hideKeyboard

Hides keyboard.

my.setStorage

Stores the data in the specified key in the local cache, which overlaps with the original data corresponding to the key.

my.getStorage

Gets cached data.

my.removeStorage

Removes cached data.

my.clearStorage

Clears local data cache.

my.tradePay

Initiates a payment.

my.navigateToMiniProgram

Jumps to other mini programs.

my.navigateBackMiniProgram

Returns to the previous Mini Program, only when another Mini Program jumps to the current Mini Program.

my.getClipboard

Gets the clipboard data.

my.setClipboard

Sets the clipboard data.

my.vibrate

Invokes the vibrate ability of the device.

my.makePhoneCall

Makes a phone call.

my.multiLevelSelect

Selects in multiple levels.

my.choosePhoneContact

Chooses the phone number of a contact person

my.getLocation

Gets the current geographical location of the user.

b. Open APIs

Depending on the wallet capabilities, you can use different open APIs.

Step 3: Release the mini program

You can request to release the mini program after the development. Before you submit the release request for approval, you need to check if all the required information is filled in. Enter the required information under Mini Programs > Info if you find some required information is missing. For more information, see Release Mini Programs and Approvals.

Now you have completed the process of transforming the HTML app into a mini program. You can start to manage the mini program on the platform. For more information, see Manage Mini Program.

Precautions

Browser compatibility

When the page is running in a browser, mini program JSAPIs cannot be called. You need to identify whether the page is running in a mini program or a browser by UserAgent, and then take actions accordingly.

See the following sample codes for reference:

copy
if (/MiniProgram/.test(navigator.userAgent)) {
    my.tradePay(params)
} else {
    // process payment in other browsers.
}

UserAgent

UserAgent which is retrieved via navigator.userAgent has some specific fields like MiniProgram, which can be used to identify whether the web page runs as an HTML mini program.

For a whole UserAgent, see the following sample codes for reference:

copy
Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/18D46 ChannelId(35) Ariver/1.0.11 Griver/2.23.0 AppContainer/1.9.1 MiniProgram

Restrictions

Reserved objects

my.JSBridge is reserved for global objects defined in the PWA runtime, and you cannot modify them.

console.log

The PWA runtime strongly depends on the default console.log object in the web context, which cannot be overridden or modified.

More information

Manage Mini Programs

Mini Program types