iwa domain

set_ready

Stories addressed

• The IWA has finished loading its core code and is declaring to the native app that it is ready to handle window.communicate events.

URL

liquidstate://iwa/set_ready?request=URLENCODED_REQUEST_OBJECT

Request data

None

Response

No response

navigate

Stories addressed

• Navigate from an IWA to another IWA, with a route specified

• Navigate to a different route in the same IWA

• Navigate from a native view to an IWA

• Optionally: change tab before navigation (ignored for linear apps)

URL

liquidstate://iwa/navigate?request=URLENCODED_REQUEST_OBJECT

Request data

Property name	Type	Required	Description
webapp_id	String	No	Default value: current IWA's webapp_id
entrypoint	String	No	Default value: "default"
route	String	No	Default value: "/"
transition	String	No	Possible values: push replace modal Default value: "push" Specifies how the next view or activity should be presented. The default is “push”, which is equivalent to the platform’s default (e.g. “slide from the right hand side on iOS”).
latest	Boolean	No	Default value: true if navigate to other webapp id or no local copy of the webapp false if navigating to the same webapp id
tab_id	String	No	Indicates that the equivalent of a switch_tab event should be executed prior to this navigate event. Not applicable to linear apps. The value must be a tab defined in the app config at launch.

Example request data

{
    "webapp_id": "login",
    "entrypoint": "default",
    "route": "/",
    "replace": true,
    "latest": true,
}

Response

No response. Second web app will get window.communicate call with purpose = navigate.

navigate_back

Stories addressed

• Navigate from a route back to another route on the navigation stack, with a route id specified

• Navigate from a route back to the previous route

URL

liquidstate://iwa/navigate_back?request=URLENCODED_REQUEST_OBJECT

Request data

Property name	Type	Required	Description
webapp_id	String	No	Default value: null (equivalent to "routes belonging to any IWA")
route_id	String	No	Default value: null skip all other routes until a route with a matching id is found. The default is null, meaning any route id".

A route must match both webapp_id and route_id to be navigated to.

Example request data

{
    "webapp_id": "myapp",
    "route_id": "home"
}

Response

No response. When displaying the mathcing route again, the native app will send the original navigate event to the IWA, with all its data, for example:

window.communicate({
    "purpose": "navigate",
    "route": "/",
    "params": {
        "querystringparam1": "value"
    },
    "context": {
        "product_id": "com.example.app123.doc1",
        "page_slug": "page-1"
    }
})

trigger_action

Stories addressed

• An action defined by a web app is triggered within the native UI (presumably toolbar or navabar button was tapped)

• The current IWA wants to initiate a workflow which typically starts with an action

URL

liquidstate://iwa/navigate?request=URLENCODED_REQUEST_OBJECT

Request data

Property name	Type	Required	Description	Default
id	String	Yes	The identifier of the action to be triggered. Note the id is unique per route (see webapp.json file).	​
params	Object	No	An object listing parameter properties and their values which should override default values.	{}

Example request data

{
    "id": "edit",
    "params": {
        "edit-mode": "advanced"
    }
}

Response data

Property name	Type	Required	Description
id	String	Yes	the identifier of the action being triggered
params	Boolean	No	An object of key / value properties. The values are the default ones from the action’s definition (see webapp.json file), overridden by the ones specified in the request.

Example response

window.communicate({
    "purpose": "response",
    "request_id": "UUID",
    "event_type": "trigger_action",
    "response_data": {
        "id": "edit",
        "params": {
            "edit-mode": "advanced"
        }
    }
})

Trigger action event initiated by the native app

Most of the time, actions are not triggered by the IWA but by the user tapping/clicking on a button which was presented to them within the native UI according to the IWA’s definition.

In this case there is no request/response flow but simply a window.communicate(...) event from the native to the IWA, with its purpose set to trigger_action.

Comm event data

Similar to the response_data above but at the root of the event object.

Example comm event

window.communicate({
    "purpose": "trigger_action",
    "id": "edit",
    "params": {
        "edit-mode": "advanced"
    }
})

handle_share (deprecated)

Note

handle_share events are deprecated in favour of the upcoming Service IWA feature

Stories addressed

• The native app had information shared with it by the OS or another app and passes it on to its default IWA.

• This not a request/response event, so its data sits at the root of the event object.

Comm event

Comm event data

Property name	Type	Required	Description
source	String	Yes	A string identifying the source of the share (other app id etc.)
files	array of objects of type File (see below)	No	​
info	An object of key/value properties	No	This information is open-ended and the IWA is left to interprete it.

File object properties:

Property name	Type	Required	Description
path	String	Yes	​
mime_type	String	No	​
size	null or Number	No	size of the file in bytes. Null if the size cannot be obtained.

Example comm event

window.communicate({
    "purpose": "handle_share",
    "source": "com.example.otherapp",
    "files": [
        {
            "path": "file:///path/to/local/file.png",
            "mime_type": "image/png"
        }
    ],
    "info": {
        "datetime": "2017-08-02 13:42:57"
    }
})