This API is reliable and breaking changes are unlikely.
Syntax
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/
Version history
| Version state | Details |
|---|---|
| Introduced | 2.2 |
| Updated | Sense February 2018 |
Overview
The App Integration API provides parameters that can be used to create an URL that returns a complete HTML page containing the embedded app. This URL can be embedded in a web page, for example by including it in an iframe.
It allows you to pass parameters to an app and to open an app with one or several selections applied.
The App Integration API is built on top of the Base URL. You can add additional parameters on top of the Base URL which defines the behavior of the App Integration API.
Base URL
The Base URL is constant and defines the location of the app.
Syntax: Base URL
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/
The following parameters must be defined to integrate the Qlik Sense app into your web site.
| Parameter | Description |
|---|---|
| machinename | servername |
Specifies the path to the local machine or the server on which the app is located.
|
| virtual proxy |
This parameter is optional depending on server configuration for the server. Specifies the virtual proxy to use. |
| appid |
App id of the referenced app.
|
| sheetid | Sheet id of the referenced sheet. |
Retrieving the virtual proxy prefix programmatically
To get the virtual proxy prefix programmatically, you can use the following code in a browser console:
var prefix = window.location.pathname.substr( 0, window.location.pathname.toLowerCase().lastIndexOf( "/sense/app" ) + 1 );
Additional parameters
In addition to the Base URL, you can also pass parameters for bookmarks, options and selections.
Bookmarks
bookmark/{bookmarkid}
You add a bookmark definition by stating the bookmark id in addition to the Base URL.
Syntax: Base URL + bookmark
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/bookmark/{bookmarkid}
The bookmark id can be obtained by using the Single configurator.
Mashups: Obtaining app IDs and object IDs
Themes
theme/{themename}
You add a theme definition by stating the name of the theme in addition to the Base URL. If no theme is stated, the default theme set in the Qlik Sense app will be used.
The theme name is case sensitive.
Syntax: Base URL + theme
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/theme/{themename}
Options
options/{option}
You can add option definitions in addition to the Base URL. Options will be applied before bookmarks and selections.
The following options are currently supported:
| Option | Description |
|---|---|
| clearselections | Clears all selections (in all states) made in the app. |
| {state}::clearselections |
Clears all selections in the defined state. state - the name of the alternate state Example: Clear all selections in the default state $::clearselections Example: Clear all selections in one state My state::clearselections Example: Clear all selections in multiple states My first state::clearselections;My second state::clearselections |
Syntax: Base URL + option
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/options/{option}
Selections
Select in the default state
select/{field}/{[value1;value2]} or select/{$::field}/{[value1;value2]}
Select in a defined state
select/{state::field}/{[value1;value2]}
The following parameters are part of the selection definitions you add to a base URL:
| Parameter | Description |
|---|---|
| state | The name of the alternate state (Optional). |
| field | The name of the field. |
| value | The name of the value. |
Selection definitions can be added to the Base URL. You can make selections in a single field or in multiple fields. Multiple values are semicolon separated.
You can also make selections in one or multiple states.
Syntax: Base URL + selection in single field (in default state)
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{field}/{value1;value2}
Syntax: Base URL + selection in single field that has text representation of numeric values (in default state)
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{field}/{[value1];[value2]}
Syntax: Base URL + selections in multiple fields (in default state)
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{field}/{value1;value2}/select/{field2}/{value1;value2}
Syntax: Base URL + selections in one state
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{state::field}/{[value1];[value2]}
Syntax: Base URL + selections in multiple states
http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{state1::field}/{[value1];[value2]}/select/{state2::field}/{[value1];[value2]}
Error handling
Faulty definitions of bookmarks, options or selections are ignored.
Limitations
Solutions created with App Integration API may not work when the URL length is too long. You can increase the max length of the URL segment by adjusting one key in the Windows registry:
- HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters\UrlSegmentMaxLength
Set it to a suitable length. Max length is 32766 and 0 means no limit.