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.
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 [=Document/global application lifecycle events=] and MiniApp [=Document/page lifecycle events=]. Developing MiniApp with knowledge of the MiniApp [=Document/global application lifecycle states=] and MiniApp [=Document/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.
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:
MiniApp initialization
MiniApp running in foreground
MiniApp running in background
MiniApp in error
MiniApp unloading
For each MiniApp, after [=Document/initialization=], it will be either [=Document/running in foreground=] or [=Document/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 [=Document/running in background=].
When user reopens the same MiniApp, MiniApp will switch from [=Document/running in background=] to [=Document/running in foreground=].
[=Document/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.
This spec formalizes five global application lifecycle states to support the above [=Document/global application lifecycle events=]:
The mapping to existing Web specifications such as Service Workers is listed in MiniApp Lifecycle Explainer.
GlobalState enum
The MiniApp [=Document/global application lifecycle states=] are reflected in the API via the {{GlobalState}} enum.
enum GlobalState {
"launched", "shown", "hidden", "error", "unloaded"
};
The GlobalState enum is used to represent the [=Document/global application lifecycle states=].
The "launched" enum value represents the [=Document/launched=] [=Document/global application lifecycle states=].
The "shown" enum value represents the [=Document/shown=] [=Document/global application lifecycle states=].
The "hidden" enum value represents the [=Document/hidden=] [=Document/global application lifecycle states=].
The "error" enum value represents the [=Document/error=] [=Document/global application lifecycle states=].
The "unloaded" enum value represents the [=Document/unloaded=] [=Document/global application lifecycle states=].
[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;
};
On getting, the globalState attribute MUST return {{GlobalState}}.
The inputObject contains the basic information of the MiniApp, such as page path for the MiniApp, source info for the MiniApp.
The lifecycleError contains error indication information for [=Document/in error=] event type .
The ongloballaunched attribute is an event handler IDL attribute for the [=Document/initialization=] event type. Once this event is triggered, globalState will be set to [=Document/launched=].
The onglobalshown attribute is an event handler IDL attribute for the [=Document/running in foreground=] event type. Once this event is triggered, globalState will be set to [=Document/shown=].
The onglobalhidden attribute is an event handler IDL attribute for the [=Document/running in background=] event type. Once this event is triggered, globalState will be set to [=Document/hidden=].
The onglobalerror attribute is an event handler IDL attribute for the [=Document/in error=] event type. Once this event is triggered, globalState will be set to [=Document/error=].
The onglobalunloaded attribute is an event handler IDL attribute for the [=Document/unloading=] event type. Once this event is triggered, globalState will be set to [=Document/unloaded=].
[Exposed=Window]
interface InputObject {
readonly attribute DOMString pagePath;
readonly attribute DOMString referrerInfo;
readonly attribute DOMString lang;
readonly attribute TextDirection dir;
};
TextDirection enum
enum TextDirection {
"auto",
"ltr",
"rtl"
};
The text-direction values are the following, implying that the value of the human-readable members is by default:
autoltrrtlOn getting, the pagePath attribute MUST return the page path for current MiniApp.
The referrerInfo attribute contains the source info for the MiniApp, including MiniApp ID, and optional extra data including human readable value.
The value of the lang attribute MUST be a well-formed language tag as defined by [[BCP47]].
The dir attribute specifies the base direction for the values of the `referrerInfo` attribute if it contains human readable value.
[Exposed=Window]
interface LifecycleError {
readonly attribute DOMString errorDescription;
readonly attribute DOMString lang;
readonly attribute TextDirection dir;
};
The errorDescription attribute is a developer-friendly textual description of the [=Document/error=] [=Document/global application lifecycle states=].
The value of the lang attribute MUST be a well-formed language tag as defined by [[BCP47]].
The dir attribute specifies the base direction for the values of the `errorDescription` attribute.
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:
MiniApp page loading
MiniApp page first render ready
MiniApp page running in foreground
MiniApp page running in background
MiniApp page unloading
When user firstly opens a MiniApp, the MiniApp [=Document/initialization=] starts. [=Document/View layer=] and [=Document/Logic layer=] will simultaneously start the initialization.
Once [=Document/Logic layer=] initialization is completed, it creates a MiniApp instance. Simultaneously, once [=Document/View layer=] initialization is completed, it starts the MiniApp [=Document/page loading=], to establish communication channel between [=Document/View layer=] and [=Document/Logic layer=].
After the communication channel is established, [=Document/Logic layer=] sends the initial data to [=Document/View layer=] to start the [=Document/first render=].
If [=Document/View layer=] completes the page UI update based on the inputted initial data from [=Document/Logic layer=], the [=Document/first render=] is considered as completed, and then [=Document/View layer=] notifies [=Document/Logic layer=], to trigger the MiniApp [=Document/page first render ready=].
Afterwards, user can interact with MiniApp. [=Document/View layer=] can be triggered to deliver user event to [=Document/Logic layer=] for further processing, then [=Document/Logic layer=] returns result data to [=Document/View layer=] for re-render.
If user leaves the current MiniApp page (e.g., by navigating to another MiniApp page), MiniApp [=Document/page running in background=] is triggered. If the MiniApp page is reopened, MiniApp [=Document/page running in foreground=] is triggered.
If user closes the current MiniApp page, MiniApp [=Document/page unloading=] is triggered.
This spec formalizes five MiniApp page lifecycle states to support the above [=Document/page lifecycle events=]:
The mapping to existing Web specifications such as Page Visibility is listed in MiniApp Lifecycle Explainer.
PageState enum
The MiniApp [=Document/page lifecycle states=] are reflected in the API via the {{PageState}} enum.
enum PageState {
"loaded", "ready", "shown", "hidden", "unloaded"
};
The PageState enum is used to represent the MiniApp [=Document/page lifecycle states=].
The "loaded" enum value represents the [=Document/page loaded=] [=Document/page lifecycle states=].
The "ready" enum value represents the [=Document/page ready=] [=Document/page lifecycle states=].
The "shown" enum value represents the [=Document/page shown=] [=Document/page lifecycle states=].
The "hidden" enum value represents the [=Document/page hidden=] [=Document/page lifecycle states=].
The "unloaded" enum value represents the [=Document/page unloaded=] [=Document/page lifecycle states=].
[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;
};
On getting, the pageState attribute MUST return {{PageState}}.
The pageInputObject contains pageInputQuery for loading the MiniApp page.
The onpageloaded attribute is an event handler IDL attribute for the [=Document/page loading=] event type. Once this event is triggered, pageState will be set to [=Document/page loaded=].
The onpageready attribute is an event handler IDL attribute for the [=Document/page first render ready=] event type. Once this event is triggered, pageState will be set to [=Document/page ready=].
The onpageshown attribute is an event handler IDL attribute for the [=Document/page running in foreground=] event type. Once this event is triggered, pageState will be set to [=Document/page shown=].
The onpagehidden attribute is an event handler IDL attribute for the [=Document/page running in background=] event type. Once this event is triggered, pageState will be set to [=Document/page hidden=].
The onpageunloaded attribute is an event handler IDL attribute for the [=Document/page unloading=] event type. Once this event is triggered, pageState will be set to [=Document/page unloaded=].
[Exposed=Window]
interface PageInputObject {
readonly attribute DOMString pageInputQuery;
};
The pageInputQuery attribute contains inputted query for the MiniApp page.
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);
MiniApp [=Document/running in foreground=] and [=Document/running in background=] event enables developer to know when a MiniApp is visible. By use of [=Document/page running in foreground=] event, developer can choose to process and hide the sensitive data, before MiniApp page switches to be [=Document/page running in foreground=]; the [=Document/page unloaded=] event provides a notification that the page is being unloaded.
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.
MiniApp Lifecycle involves (sometimes) responding to user interaction, e.g., {{GlobalState}} indicates whether the MiniApp is [=Document/shown=] or [=Document/hidden=]; {{PageState}} indicates whether the MiniApp page is [=Document/page shown=] or [=Document/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.