App Integration API

STABLE.
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

Introduced 2.2
Updated Sense February 2018

Overview

As the App Integration API relies on the Qlik Sense Hub, it is not available in a QAP environment.

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.

Be aware that the Base URL might change in future releases.

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.

  • https://<servername>/
  • http://localhost:4848/ for Qlik Sense Desktop environment.
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.

  • App name including full path for Qlik Sense Desktop environment.
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

If a bookmark points to another sheet than the one you defined in the URL, you will automatically be redirected to the correct sheet.

Themes

Theme support in App Integration API was added in Qlik Sense February 2018.

theme/{theme-id}

You add a theme definition by stating the theme ID in addition to the Base URL. If no theme is stated, the default theme set in the Qlik Sense app will be used.

Syntax: Base URL + theme

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/theme/{themeid}

Options

options/{option}

You can add option definitions in addition to the Base URL. The following options are currently supported:

Option Description
clearselections Clears all selections made in the app before applying bookmarks and selections.

Syntax: Base URL + option

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/options/{option}

Selections

select/{field}/{[value1;value2]}

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.

For selections containing numeric values and search terms, the text representation should be added within square brackets, as in [value1].

Syntax: Base URL + selection in single field

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

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{field}/{[value1];[value2]}

Syntax: Base URL + selections in multiple fields

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{field}/{value1;value2}/select/{field2}/{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.

We recommend that you investigate the impact to other programs on the machine, as changing these settings is a system-wide change.

See also: