The WebActivity API provides a way for applications to delegate an activity to another application. An activity is something a user wants to do: pick an image, play a video, etc. Apps can declare themselves as an activity hander, for example, Gallery App and installed 3rd-party photo-manage Apps can all be candidates when users request to pick photos. Usually such list of choices are provided to users.
WebActivity interface exposes to both Window and Worker scope, in the window scope, creation of WebActivity is allowed when the requester application is visible (in the foreground). In the worker scope, WebActivity is allowed iff permission worker-activity is declared and granted, otherwise an insecure error will throw and the creation of WebActivity returns nullptr.
#Starting an activity
The constructor of
WebActivity takes a name of the activity and an optional Object specifying its filter type or other information, for example:
In this example, we are trying to initiate a "pick" activity, and the handlers should support providing at least jpeg images. Please note that the constructor may throw and return a null object with illegal access.
Then, start the activity by
start() method, if an activity handler (i.e. Gallery App) is launched and the request is handled successfully, the promise will be resolved with the picking result.
Please note that one WebActivity instance starts once, duplicate calls of start() is rejected.
#Cancel an activity
To cancel a started activity, use
cancel(), and the pending promise of
start() will also be rejected.
#Handle an activity
Once the user has picked an activity handler (or picked by System App secretly),
SystemMessageEvent with name activity will be dispatched to the event handler on its service worker, unlike other system messages,
SystemMessageData has a property
WebActivityRequestHandler, which provides methods to resolve or reject the pending promise of
Please note that per spec of ServiceWorkerGlobalScope, the activity handler is not persisted across the termination/restart cycle of worker. See ServiceWorkerGlobalScope for more details.
 Developers should keep in mind that the ServiceWorker state is not persisted across the termination/restart cycle, so each event handler should assume it's being invoked with a bare, default global state.
systemmessage event of name activity, handler can decide whether to launch the application window to perform user interaction, by using ServiceWorker API,
Clients.openWindow(). Or can pass back results with
WebActivityRequestHandler.postResult() directly. Suggest using
postMessage() method to communicate between main scripts and service worker script.
WebActivityRequestHandler.postError() to send back an error message if something goes wrong.
WebActivityRequestHandler.source is a
WebActivityOptions object, representing information sent from activity requester.
- A string represents the name of the activity request.
- An object represents data that is sent from activity requester.
WebActivityOptionsobject contains the information about the current activity. Set by the app who starts the activity.
- Send back response and resolve the promise of app that starts the activity.
- Send back error message and reject the promise of app that starts the activity.
#Open its window with Clients.openWindow
#Register an App as an activity handler
App can register itself as an activity handler to handle one or more activities. Besides declaring activity related information in the app manifest, app has to set up the service worker script in its manifest first.
#Set up service worker registration
options object is optional, as defined in ServiceWorkerContainer.register()#Syntax, for example:
In the most case the above example is good enough.
#Set up activity handler registration
In general, please reference Registering an App as an activity handler
#New attributes and updates for activity handler description
No need to specify the href anymore.
No need to specify the disposition anymore.
Same as before.
Same as before.
An array of origins. This is for handler to limit its usage to specific users, will filter out callers who's origin is not in the list. For example, setting
"allowedOrigins": ["http://testapp1.localhost", "http://testapp2.localhost"], only allows requests made from "http://testapp1.localhost" or "http://testapp2.localhost".