MiniApp Lifecycle

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2022/WD-miniapp-lifecycle-20220324/
Latest published version:
https://www.w3.org/TR/miniapp-lifecycle/
Latest editor's draft:
https://w3c.github.io/miniapp-lifecycle/
History:
https://www.w3.org/standards/history/miniapp-lifecycle
Commit history
Editors:
Qing An (Alibaba)
Haoyang Xu (Alibaba)
Former editor:
Xia Xu (Alibaba)
Feedback:
GitHub w3c/miniapp-lifecycle (pull requests, new issue, open issues)

Abstract

This specification defines the MiniApp lifecycle events and the process to manage MiniApp and each page's lifecycle. Implementing this specification enables the user agent to manage the lifecycle events of both the global application lifecycle and the page lifecycle.

Status of This Document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the MiniApps Working Group as a Working Draft using the Recommendation track.

Publication as a Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 2 November 2021 W3C Process Document.

1. Background

As described in MiniApp Standardization White Paper, in a miniapp, the View layer is separated from the Logic layer. The View layer is responsible for rendering MiniApp pages, including Web rendering and native rendering, which can be considered as hybrid rendering. The Logic layer is implemented with JavaScript Worker. The Logic layer is responsible for MiniApp’s event processing, API calling and lifecycle management.

MiniApp lifecycle mechanism provides a means to manage MiniApp's View layer and Logic layer through the MiniApp global application lifecycle events and MiniApp page lifecycle events. Developing MiniApp with knowledge of the MiniApp global application lifecycle states and MiniApp page lifecycle states can lead to improved user experiences. MiniApp lifecycle includes a set of events, with which MiniApp can choose to alter its behavior based on its state.

2. MiniApp Global Application Lifecycle

2.1 MiniApp Global Application Lifecycle Events

This spec defines what the lifecycle of a MiniApp global application is and adds definition to enable MiniApp to respond to four important global application lifecycle events commonly performed by MiniApp:

For each MiniApp, after initialization, it will be either running in foreground or running in background.

When user chooses to close the MiniApp by clicking the close button on MiniApp, or go to the mobile phone’s home screen, the MiniApp will not be destroyed immediately, but switch to be running in background.

When user reopens the same MiniApp, MiniApp will switch from running in background to running in foreground.

Only when MiniApp runs in the background for more than a specific time duration (e.g., 5 minutes), or occupies too much system resources in the background, the MiniApp will be destroyed.

2.2 MiniApp Global Application Lifecycle States

This spec formalizes four global application lifecycle states to support the above global application lifecycle events:

launched
Lifecycle state for MiniApp initialization. This means that the MiniApp initialization is completed, and it is triggered only once. Through this event, developer can obtain the information of the MiniApp, such as URI, source info, etc.
shown
Lifecycle state for MiniApp running in foreground. It is triggered once the MiniApp enters the launched state, or once the MiniApp switches to be running in foreground from running in background.
hidden
Lifecycle state for MiniApp running in background. It is triggered once the MiniApp switches to be running in background from running in foreground.
error
Lifecycle state for MiniApp in error. It is triggered once the MiniApp is confronted with script error.

The mapping to existing Web specifications such as Service Workers is listed in MiniApp Lifecycle Explainer.

2.3 GlobalState enum

The MiniApp global application lifecycle states are reflected in the API via the GlobalState enum.

WebIDLenum GlobalState {
    "launched", "shown", "hidden", "error"
};

The GlobalState enum is used to represent the global application lifecycle states.

The "launched" enum value represents the launched global application lifecycle states.

The "shown" enum value represents the shown global application lifecycle states.

The "hidden" enum value represents the hidden global application lifecycle states.

The "error" enum value represents the error global application lifecycle states.

2.4 MiniApp Global Application Lifecycle interface and callbacks

WebIDL [Exposed=Window]
 interface Global {
  undefined getGlobalState (
      GlobalState globalState,
      GlobalLaunchedCallback globalLaunchedCallback,
      GlobalShownCallback globalShownCallback,
      GlobalHiddenCallback globalHiddenCallback,
      GlobalErrorCallback globalErrorCallback
  );
 };

callback GlobalLaunchedCallback = undefined (
  InputObject inputObject
);

callback GlobalShownCallback = undefined (
  InputObject inputObject
);

callback GlobalHiddenCallback = undefined (
);

callback GlobalErrorCallback = undefined (
  LifecycleError lifecycleError
);

2.4.1 getGlobalState() method

When getGlobalState() is invoked, the user agent MUST:

  1. Request global application lifecycle state, passing globalLaunchedCallback, globalShownCallback, globalHiddenCallback, and globalErrorCallback.
  2. Return undefined.

2.4.2 globalLaunchedCallback

If MiniApp's first page is ready to load, invoke GlobalLaunchedCallback.

2.4.3 globalShownCallback

If MiniApp enters the shown global application lifecycle states, or if MiniApp switches to be running in foreground from running in background, invoke GlobalShownCallback.

2.4.4 globalHiddenCallback

If MiniApp switches to be running in background from running in foreground, invoke GlobalHiddenCallback.

2.4.5 globalErrorCallback

If MiniApp MiniApp is confronted with script error, invoke GlobalErrorCallback.

2.5 InputObject interface

WebIDL[Exposed=Window]
interface InputObject {
    readonly attribute DOMString inputQuery;
    readonly attribute DOMString pagePath;
    readonly attribute DOMString referrerInfo;
};

2.5.1 inputQuery attribute

The inputQuery attribute contains inputted query for the MiniApp.

2.5.2 pagePath attribute

The pagePath attribute contains the page path for current MiniApp.

Note

2.5.3 referrerInfo attribute

The referrerInfo attribute contains the source info for the MiniApp, including MiniApp ID, and optional extra data.

2.6 LifecycleError interface

WebIDL[Exposed=Window]
interface LifecycleError {
    readonly attribute DOMString errorDescription;
};

2.6.1 errorDescription attribute

The errorDescription attribute is a developer-friendly textual description of the error global application lifecycle states.

3. MiniApp Page Lifecycle

3.1 MiniApp Page Lifecycle Events

This spec defines what the lifecycle of a MiniApp page is and adds definition to enable MiniApp to respond to five important page lifecycle events commonly performed by MiniApp:

Note
  1. When user firstly opens a MiniApp, the MiniApp initialization starts. View layer and Logic layer will simultaneously start the initialization.

  2. Once Logic layer initialization is completed, it creates a MiniApp instance. Simultaneously, once View layer initialization is completed, it starts the MiniApp page loading, to establish communication channel between View layer and Logic layer.

  3. After the communication channel is established, Logic layer sends the initial data to View layer to start the first render.

  4. If View layer completes the page UI update based on the inputted initial data from Logic layer, the first render is considered as completed, and then View layer notifies Logic layer, to trigger the MiniApp page first render ready.

  5. Afterwards, user can interact with MiniApp. View layer can be triggered to deliver user event to Logic layer for further processing, then Logic layer returns result data to View layer for re-render.

  6. If user leaves the current MiniApp page (e.g., by navigating to another MiniApp page), MiniApp page running in background is triggered. If the MiniApp page is reopened, MiniApp page running in foreground is triggered.

  7. If user closes the current MiniApp page, MiniApp page unloading is triggered.

3.2 MiniApp Page Lifecycle States

This spec formalizes five MiniApp page lifecycle states to support the above page lifecycle events:

page loaded
Lifecycle state for MiniApp page loading. This means that MiniApp page loading is completed. At this moment, Logic layer has obtained initialization data, and developer can obtain the path of current MiniApp page as well as the path’s query.
page ready
Lifecycle state for MiniApp page first render ready. It is triggered once the MiniApp page first render is completed. At this moment, the page UI can be configured.
page shown
Lifecycle state for MiniApp page running in foreground. It is triggered once the page switches to be page running in foreground from page running in background. At this moment, developer can update data and refresh page.
page hidden
Lifecycle state for MiniApp page running in background. It is triggered once the MiniApp page switches to be page running in foreground to page running in background.
page unloaded
Lifecycle state for MiniApp page unloading. It is triggered once the MiniApp page is closed.

The mapping to existing Web specifications such as Page Visibility is listed in MiniApp Lifecycle Explainer.

3.3 PageState enum

The MiniApp page lifecycle states are reflected in the API via the PageState enum.

WebIDLenum PageState {
    "loaded", "ready", "shown", "hidden", "unloaded"
};

The PageState enum is used to represent the MiniApp page lifecycle states.

The "loaded" enum value represents the page loaded page lifecycle states.

The "ready" enum value represents the page ready page lifecycle states.

The "shown" enum value represents the page shown page lifecycle states.

The "hidden" enum value represents the page hidden page lifecycle states.

The "unloaded" enum value represents the page unloaded page lifecycle states.

3.4 MiniApp Page Lifecycle interface and callbacks

WebIDL [Exposed=Window]
 interface Page {
  undefined getPageState (
      PageState pageState,
      PageLoadedCallback pageLoadedCallback,
      PageReadyCallback pageReadyCallback,
      PageShownCallback pageShownCallback,
      PageHiddenCallback pageHiddenCallback,
      PageUnloadedCallback pageUnloadedCallback
  );
 };

callback PageLoadedCallback = undefined (
  PageInputObject pageInputObject
);

callback PageReadyCallback = undefined (
);

callback PageShownCallback = undefined (
);

callback PageHiddenCallback = undefined (
);

callback PageUnloadedCallback = undefined (
);

3.4.1 getPageState() method

When getPageState() is invoked, the user agent MUST:

  1. Request page lifecycle state, passing pageLoadedCallback, pageReadyCallback, pageShownCallback, pageHiddenCallback, and pageUnloadedCallback.
  2. Return undefined.

3.4.2 pageLoadedCallback

If a communication channel has been established between View layer and Logic layer, invoke PageLoadedCallback.

3.4.3 pageReadyCallback

If MiniApp page first render is completed, invoke PageReadyCallback.

3.4.4 pageShownCallback

If MiniApp page switches to be page running in foreground from page running in background, invoke PageShownCallback.

3.4.5 pageHiddenCallback

If MiniApp page switches to be page running in background from page running in foreground, invoke PageHiddenCallback.

3.4.6 pageUnloadedCallback

If MiniApp page is closed, invoke PageUnloadedCallback.

3.5 PageInputObject interface

WebIDL[Exposed=Window]
interface PageInputObject {
    readonly attribute DOMString pageInputQuery;
};

3.5.1 pageInputQuery attribute

The pageInputQuery attribute contains inputted query for the MiniApp page.

4. Privacy and Security

This section is non-normative.

MiniApp running in foreground and running in background event enables developer to know when a MiniApp is visible. By use of page running in foreground event, developer can choose to process and hide the sensitive data, before MiniApp page switches to be page running in foreground; the page unloaded event provides a notification that the page is being unloaded.

A. References

A.1 Informative references

[webidl]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/