> For the complete documentation index, see [llms.txt](https://docs.liquid-gears.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.liquid-gears.com/iwa-framework/events/iwa.md).

# iwa domain

## set\_ready

### Stories addressed <a href="#stories-addressed-1" id="stories-addressed-1"></a>

* 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 <a href="#url-1" id="url-1"></a>

```
liquidstate://iwa/set_ready?request=URLENCODED_REQUEST_OBJECT
```

### Request data <a href="#request-data-1" id="request-data-1"></a>

None

### Response <a href="#response-data-1" id="response-data-1"></a>

No response

## navigate <a href="#navigate" id="navigate"></a>

### Stories addressed <a href="#stories-addressed-1" id="stories-addressed-1"></a>

* 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 <a href="#url-1" id="url-1"></a>

```
liquidstate://iwa/navigate?request=URLENCODED_REQUEST_OBJECT
```

### Request data <a href="#request-data-1" id="request-data-1"></a>

| 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       | <p>Possible values:</p><ul><li>push</li><li>replace</li><li>modal</li></ul><p>Default value: "push"</p><p>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”).</p> |
| latest        | Boolean | No       | <p>Default value:</p><ul><li>true if navigate to other webapp id or no local copy of the webapp</li><li>false if navigating to the same webapp id</li></ul>                                                                                                                                     |
| tab\_id       | String  | No       | <p>Indicates that the equivalent of a switch\_tab event should be executed prior to this navigate event.</p><p>Not applicable to linear apps.</p><p>The value must be a tab defined in the app config at launch.</p>                                                                            |

#### Example request data <a href="#example-request-data" id="example-request-data"></a>

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

### Response <a href="#response-data-1" id="response-data-1"></a>

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

## navigate\_back <a href="#navigate_back" id="navigate_back"></a>

### 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 <a href="#url-1" id="url-1"></a>

```
liquidstate://iwa/navigate_back?request=URLENCODED_REQUEST_OBJECT
```

### Request data <a href="#request-data-1" id="request-data-1"></a>

| Property name | Type   | Required | Description                                                                                                                                   |
| ------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| webapp\_id    | String | No       | Default value: null (equivalent to "routes belonging to any IWA")                                                                             |
| route\_id     | String | No       | <p>Default value: null</p><p>skip all other routes until a route with a matching id is found. The default is null, meaning any route id".</p> |

A route must match both webapp\_id and route\_id to be navigated to.

#### Example request data <a href="#example-request-data" id="example-request-data"></a>

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

### Response <a href="#response-data-1" id="response-data-1"></a>

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:

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

## trigger\_action <a href="#trigger_action" id="trigger_action"></a>

### Stories addressed <a href="#stories-addressed-1" id="stories-addressed-1"></a>

* 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 <a href="#url-1" id="url-1"></a>

```
liquidstate://iwa/navigate?request=URLENCODED_REQUEST_OBJECT
```

### Request data <a href="#request-data-1" id="request-data-1"></a>

| 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 <a href="#example-request-data" id="example-request-data"></a>

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

### Response data <a href="#response-data-1" id="response-data-1"></a>

| 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 <a href="#example-response-1" id="example-response-1"></a>

```javascript
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 <a href="#trigger-action-event-initiated-by-the-native-app" id="trigger-action-event-initiated-by-the-native-app"></a>

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

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

## handle\_share (deprecated) <a href="#handle_share" id="handle_share"></a>

### Note

handle\_share events are deprecated in favour of the upcoming Service IWA feature

### Stories addressed <a href="#stories-addressed-2" id="stories-addressed-2"></a>

* 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 <a href="#comm-event" id="comm-event"></a>

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

```javascript
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"
    }
})
```