MiniApp Lifecycle

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2023/WD-miniapp-lifecycle-20230529/
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 five 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.

unloading marks the end of the MiniApp session, and the removal of all the temporary resources from the cache. MiniApp user agents perform this removal once the MiniApp meets the criteria. When MiniApp runs in the background for more than a specific time duration (e.g., 5 minutes), or occupies too many system resources in the background, the MiniApp should be unloaded.

2.2 MiniApp Global Application Lifecycle States

This spec formalizes five 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.
unloaded
Lifecycle state for MiniApp unloading. It is triggered once the MiniApp is unloaded.

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", "unloaded"
};

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.

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

2.4 MiniApp Global Application Lifecycle interface

WebIDL[Exposed=Window]
interface Global {
 readonly attribute GlobalState globalState;
 readonly attribute InputObject inputObject;
 readonly attribute LifecycleError lifecycleError;
 attribute EventHandler ongloballaunched;
 attribute EventHandler onglobalshown;
 attribute EventHandler onglobalhidden;
 attribute EventHandler onglobalerror;
 attribute EventHandler onglobalunloaded;
};

2.4.1 globalState attribute

On getting, the globalState attribute MUST return GlobalState.

2.4.2 inputObject attribute

The inputObject contains the basic information of the MiniApp, such as page path for the MiniApp, source info for the MiniApp.

2.4.3 lifecycleError attribute

The lifecycleError contains error indication information for in error event type .

2.4.4 ongloballaunched event handler attribute

The ongloballaunched attribute is an event handler IDL attribute for the initialization event type. Once this event is triggered, globalState will be set to launched.

2.4.5 onglobalshown event handler attribute

The onglobalshown attribute is an event handler IDL attribute for the running in foreground event type. Once this event is triggered, globalState will be set to shown.

2.4.6 onglobalhidden event handler attribute

The onglobalhidden attribute is an event handler IDL attribute for the running in background event type. Once this event is triggered, globalState will be set to hidden.

2.4.7 onglobalerror event handler attribute

The onglobalerror attribute is an event handler IDL attribute for the in error event type. Once this event is triggered, globalState will be set to error.

2.4.8 onglobalunloaded event handler attribute

The onglobalunloaded attribute is an event handler IDL attribute for the unloading event type. Once this event is triggered, globalState will be set to unloaded.

2.5 InputObject interface

WebIDL[Exposed=Window]
interface InputObject {
    readonly attribute DOMString pagePath;
    readonly attribute DOMString referrerInfo;
    readonly attribute DOMString lang;
    readonly attribute TextDirection dir;
};
TextDirection enum

WebIDLenum TextDirection {    
    "auto",
    "ltr",    
    "rtl"
};

The text-direction values are the following, implying that the value of the human-readable members is by default:

auto
Directionality is determined by the Unicode Bidirectional Algorithm [UAX9] algorithm.
ltr
Left-to-right text.
rtl
Right-to-left text.

2.5.1 pagePath attribute

On getting, the pagePath attribute MUST return the page path for current MiniApp.

Note

2.5.2 referrerInfo attribute

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

2.5.3 lang attribute

The value of the lang attribute MUST be a well-formed language tag as defined by [BCP47].

2.5.4 dir attribute

The dir attribute specifies the base direction for the values of the referrerInfo attribute if it contains human readable value.

2.6 LifecycleError interface

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

2.6.1 errorDescription attribute

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

2.6.2 lang attribute

The value of the lang attribute MUST be a well-formed language tag as defined by [BCP47].

2.6.3 dir attribute

The dir attribute specifies the base direction for the values of the errorDescription attribute.

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

WebIDL[Exposed=Window]
interface Page {
    readonly attribute PageState pageState;
    readonly attribute PageInputObject pageInputObject;
    attribute EventHandler onpageloaded;
    attribute EventHandler onpageready;
    attribute EventHandler onpageshown;
    attribute EventHandler onpagehidden;
    attribute EventHandler onpageunloaded;
};

3.4.1 pageState attribute

On getting, the pageState attribute MUST return PageState.

3.4.2 pageInputObject attribute

The pageInputObject contains pageInputQuery for loading the MiniApp page.

3.4.3 onpageloaded event handler attribute

The onpageloaded attribute is an event handler IDL attribute for the page loading event type. Once this event is triggered, pageState will be set to page loaded.

3.4.4 onpageready event handler attribute

The onpageready attribute is an event handler IDL attribute for the page first render ready event type. Once this event is triggered, pageState will be set to page ready.

3.4.5 onpageshown event handler attribute

The onpageshown attribute is an event handler IDL attribute for the page running in foreground event type. Once this event is triggered, pageState will be set to page shown.

3.4.6 onpagehidden event handler attribute

The onpagehidden attribute is an event handler IDL attribute for the page running in background event type. Once this event is triggered, pageState will be set to page hidden.

3.4.7 onpageunloaded event handler attribute

The onpageunloaded attribute is an event handler IDL attribute for the page unloading event type. Once this event is triggered, pageState will be set to page unloaded.

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.

Note

4. Usage example

This section is non-normative.

Example of handling MiniApp global lifecycles:

const doGlobalLaunched = (inputObject) => {
    console.log(inputObject.pagePath);
};

global.addEventListener('globallaunched', doGlobalLaunched);

Example of handling MiniApp page lifecycles:

const doPageLoaded = (pageInputObject) => {
    console.log(pageInputObject.pageInputQuery);
};

page.addEventListener('pageloaded', doPageLoaded);

5. Security Considerations

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.

6. Privacy Considerations

This section is non-normative.

MiniApp Global Application Lifecycle interface Global introduces inputObject which involves the processing of the inputted query for the MiniApp, the page path for current MiniApp, and the source info. MiniApp Page Lifecycle interface Page introduces pageInputObject which involves the processing of the inputted query for the MiniApp page. In order to protect users from any potential unsanctioned tracking threat, it is not recommended to store these values locally. If these values are stored, these storages should be cleared when users intend to clear them.

If the inputted query for the MiniApp or the inputted query for the MiniApp page contains privacy-sensitive information (e.g. user personal data), the privacy-sensitive information shall not be in cleartext.

7. Accessibility Considerations

This section is non-normative.

MiniApp Lifecycle involves (sometimes) responding to user interaction, e.g., GlobalState indicates whether the MiniApp is shown or hidden; PageState indicates whether the MiniApp page is page shown or page hidden. The user agent should adequately communicate with the accessibility services of the MiniApp lifecycle states, e.g., on getting, the GlobalState and the PageState should return MiniApp Global Application Lifecycle states and MiniApp Page Lifecycle states correspondingly to the accessibility services.

A. References

A.1 Informative references

[BCP47]
Tags for Identifying Languages. A. Phillips, Ed.; M. Davis, Ed.. IETF. September 2009. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5646
[html]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[UAX9]
Unicode Bidirectional Algorithm. Mark Davis; Ken Whistler. Unicode Consortium. 16 August 2022. Unicode Standard Annex #9. URL: https://www.unicode.org/reports/tr9/tr9-46.html
[webidl]
Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/