app domain

List of event types part of the "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

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	a HTTP URL (path starts with “HTTP://” or “HTTPS://”) a relative location (path starts with “./”) an absolute location (path starts “file:///”)

Example request data

{
    "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

{
    "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

{
    "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

{
    "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:

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: fine = gps location, coarse = wifi “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.	latitude required : true value : numeric string longitude required : true value : numeric string accuracy required : false value : numeric string comment : accuracy of the location as a radius, units=metres. Confidence: 68% on android, unknown on iOS. Web?
error	Boolean	true if “type” is “none” otherwise not present	reason required : true value : one of “nopermission”, “disabled”, “nolocation”, “unknown” comment : “nopermission” means the user has specifically refused location permission for this app (this has a higher priority than disabled) “disabled” means that location services are turned off on the device “nolocation” means that this device cannot access location information(not expected in practice) “unknown” means the system could not access location information due to a system or app error. More descriptive information should be available in the “message” property. message required : true value : string comment : (hopefully) localised message describing the error

Example response data

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	biometrics

Example request

{
    "feature": "biometrics"
}

Response

Property name	Type	Required	Description
status	Boolean	Yes	Possible values: "unknown" means the requested feature is name not handled by this event "not_present" means the current device cannot provide this feature (ever) "disabled" means the feature is present on the device but the user has either disabled it e.g. biometrics are never available if a passcode has not been set "not_configured" means the feature is present and is not disabled, but the user must take some steps to make it usable "available" means the feature is present and configured and may be used
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: "not_present" means the current device does not have fingerprint or face-id authentication capability "disabled" means that there is no passcode registered for the device or that biometrics have been explicitly disabled by the user "not_enrolled" means biometrics are not disabled and a passcode has been set but that no fingerprints or face-id have been enrolled "available" at least one type of biometric authentication is available and fully configured
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: "touch" "face" "iris"

Example response

// 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

{
    "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.

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

{
    "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