# app domain ## reset ### Stories addressed * IWA decides that the entire app should be reload, including all its configuration and navigation contexts. ### URL ``` liquidstate://app/reset?request=URLENCODED_REQUEST_OBJECT ``` ### Request data None ### Response data No response. ## online\_status ### Stories addressed * IWA or other part of the app needs to know if the device/app is currently online or offline ### URL ``` liquidstate://app/online_status?request=URLENCODED_REQUEST_OBJECT ``` ### Request data None ### Response data | Property name | Type | Required | | ------------- | ------- | -------- | | status | Boolean | Yes | #### Example response ```javascript window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "online_status", "response_data": { "status": true } }) ``` ## open\_file ### Stories addressed * IWA or other part of the app needs to open an arbitrary file in the platform-default way. ### Description On mobile platforms, the file must be at a location accessible to the app. If the path to the file is a relative one (starts with “./”), the native must compute the absolute path according to the following: - if an IWA is sending the event, the absolute path is relative to the entrypoint file of the IWA - if the native document reading view is sesnding the event, the absolute path is relative to the HTML file being read - if another native part of the app is sending the event, the absolute path is relative to the app bundle’s root On iOS, the native would open the file in the iOS default documetn viewer (calling NSApplication:openURL). On Android, the native would trigger an intent and let the OS handle opening the file from that intent. ### URL ``` liquidstate://app/open_file?request=URLENCODED_REQUEST_OBJECT ``` ### Request data | Property name | Type | Required | Description | Default | | ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | path | String | Yes | | | #### Example request data ```javascript { "path": "./files/my_sample_file" } ``` ### Response No response. ## set\_authentication\_status ### Stories addressed * IWA logged the user in or out and lets the native app know. ### URL ``` liquidstate://app/set_authentication_status?request=URLENCODED_REQUEST_OBJECT ``` ### Request data | Property name | Type | Required | Description | | ----------------- | ------- | -------- | ----------- | | is\_authenticated | Boolean | Yes | | **Example request data** ```javascript { "is_authenticated": true } ``` ### Response No response. ## set\_notification\_presentation\_status ### Stories addressed * Login IWA needs to let the native app know that a user is ready to have notifications presesented to them. ### Description The user might not be logged oput and therefore not in a state where they should have notifications,with actions that require being authenticated presented to them. Similarly, the application logic or UI might be busy and in a state where it isn’t desirable to present the user with notifications. By default, the native app is in a *not ready* status and therefore won’t present any notification to the user until this call is made. ### URL ``` liquidstate://app/set_notification_presentation_status?request=URLENCODED_REQUEST_OBJECT ``` ### Request data | Property name | Type | Required | | ------------- | ------- | -------- | | is\_ready | Boolean | Yes | #### Example request ```javascript { "is_ready": true } ``` ### Response No response ## set\_back\_override ### Stories addressed * IWA wants to interrupt native back navigation for the current route when the user triggers it. ### URL ``` liquidstate://app/set_back_override?request=URLENCODED_REQUEST_OBJECT ``` ### Request data | Property name | Type | Required | | ------------- | ------- | -------- | | is\_enabled | Boolean | Yes | #### Example request ```javascript { "is_enabled": true } ``` ### Response No response. When the user triggers native back navigation, the native app will send the following window\.communicate event to the IWA: ```javascript window.communicate({ "purpose": "lifecycle", "id": "back" }) ``` ## user\_location ### Stories addressed * IWA needs to know the devices current geographic location ### URL ``` liquidstate://app/user_location?request=URLENCODED_REQUEST_OBJECT ``` ### Request data None ### Response | Property name | Type | Required | Description | | ------------- | ------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | String | Yes |

one of “fine”, “coarse”, “unknown”, “none”

“fine” and “coarse” match android terminology where:

“unknown” means that there is a location but it is unclear how accurate it is (e.g. the platform may not report the accuracy. An example may be the web client or iOS which does not report how it obtained the location)

“none” means no location could be returned .. see “error” for details

| | location | Object | true if “type” is NOT “none”. If “type” IS “none”, this property will notbe present. | | | error | Boolean | true if “type” is “none” otherwise not present | | #### Example response data ```javascript window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "user_location", "response_data": { "type": "fine", "location" : { "latitude" : "-27.502520099999998"", "longitude" : "153.0462454", "accuracy" : "7.21" } } }) window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "user_location", "response_data": { "type": "unknown", "location" : { "latitude" : "-27.502520099999998"", "longitude" : "153.0462454", "accuracy" : "21.34" } } }) window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "user_location", "response_data": { "type": "none", "error" : { "reason" : "nopermission", "message" : "You have not granted location permissions for this app. Please goto settings/security and grant location permission for this app" } } }) ``` ## feature\_status ### Stories addressed * IWA needs to know whether a device feature is available and any qualifying details that may be relevant ### URL ``` liquidstate://app/feature_status?request=URLENCODED_REQUEST_OBJECT ``` ### Request data | Property name | Type | Required | Possible values | | ------------- | ------ | -------- | ---------------------------- | | feature | String | Yes | | #### Example request ```javascript { "feature": "biometrics" } ``` ### Response | Property name | Type | Required | Description | | ------------- | ------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | status | Boolean | Yes |

Possible values:

| | details | Object | Yes is status is not "unknown" | This object will contain feature specific details – See "Feature Details" below | #### Feature details for biometrics | Property name | Type | Required | Description | | ------------- | --------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | feature | String | Yes | The name of the feature that was requested. | | status | String | Yes |

Possible values:

| | type | Array of String | Yes if status is "available" |

This lists the available biometric authentication methods. At the time of writing iOS devices will return a single item list containing either "face" or "touch".

Possible values:

| | | | | | #### Example response ```javascript // device does not have biometrics capability window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "feature_status", "response_data": { "status": "not_present", "detail": { feature: "biometrics", status: "not_present" } } }) // biometrics disabled or passcode/pin not set window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "feature_status", "response_data": { "status": "disabled", "detail": { feature: "biometrics", status: "disabled" } } }) // biometrics enabled but no fingerprints/face-id enrolled window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "feature_status", "response_data": { "status": "not_configured", "detail": { feature: "biometrics", status: "not_enrolled" } } }) // biometrics available on iPhone X window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "feature_status", "response_data": { "status": "available", "detail": { feature: "biometrics", status: "available" type: ["face"] } } }) // biometrics available on iPhone 6s window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "feature_status", "response_data": { "status": "available", "detail": { feature: "biometrics", status: "available" type: ["touch"] } } }) // biometrics available on Samsung S8 (with nothing disabled or un-configured) window.communicate({ "purpose": "response", "request_id": "UUID", "event_type": "feature_status", "response_data": { "status": "available", "detail": { feature: "biometrics", status: "available" type: ["touch","face","iris"] } } }) ``` ## clearall ### Stories addressed * IWA or other part of the app wants to reset the app to its initial launch condition (but not clearing authentication state). ### URL ``` liquidstate://app/clearall?request=URLENCODED_REQUEST_OBJECT ``` ### Request data None ### Response No response ## switch\_tab ### Stories addressed * IWA or other part of the app wants to change the current displayed tab (only actioned in a tabbed app) ### Request data | Property name | Type | Required | Description | | ------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | id | String | Yes | A tab id declared in the app configuration. | | reset | Boolean | False |

If true, the tab should be reset to it’s initial launch state before any route is applied.

Default value: true

| | params | String | Yes | A JSON object of arbitrary parameters to be passed onto the tab that is switched to. | #### Example request ```javascript { "id": "t1", "reset": true, "route": "/page1" } ``` ### Response No response, but... #### Message for tab being switched to The native app will issue a window\.communicate call to the tab being switched to, optionally including the "params" property specified in the original event. ```javascript window.communicate({ "purpose": "switch_tab", "params": { "foo1": "bar1", "foo2": "bar2" } }) ``` ## set\_tab\_appearance ### Stories addressed * IWA or other part of the app wants to modifiy the appearance (icon and/or text) of a tab. * Although the configuration of the list of tabs and the IWAs loaded in them never changes, this can be used by IWAs to simulate the display of different tabs to different users. ### Request data Not all tabs have to be specified in this event and it is possible to update the appearance of one or more tabs at a time. The request data is an object which has as properties the "id" of the tabs to modify, as configured in the app data. The value for each of these tab ids is an object with the following properties: | Property name | Type | Required | Description | | ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | title | String or Object | No | The text to be displayed on the tab. This can be a simple string, or an object to support translations (please refer to the app data configuration documentation). | | icon\_name | String |

Yes if you want to change the icon and "icon\_font\_name" and "icon\_code\_point" are not specified.
No otherwise.

| The name of the icon to be used from the default set of app icons. | | icon\_font\_name | String |

Yes if you want to change the icon and "icon\_name" is not specified.

No otherwise.

| The name of the font in the custom fonts configuration. | | icon\_code\_point | String |

Yes if you want to change the icon and "icon\_name" is not specified.

No otherwise.

| The code point of the glyph in the custom font file. | | hidden | Boolean | No | Specify whether this particular tab should be displayed or ommitted from the tab bar. | #### Example request ```javascript { "tab1": { "title": "Favourites", "icon_name": "star" }, "tab3": { "title": { "key": "favourites.tab-title", "translations": { "en": "Favourite", "fr": "Favoris" } }, "icon_font_name": "custom", "icon_code_point": "\U234" } } ``` ### Response No response