English Qlik Sense Developers September 2017

Single Integration API

Syntax:  

http[s]://<machinename | servername>/{virtual proxy}/single/?appid={appid}&obj={obj}&opt={options}&bookmark={bookmark}&select={selection}

Since:
  • 1.0
Updated:
  • 1.1, 3.0, 3.1

A new implementation of the Base URL was introduced in version 3.1. The legacy implementation of the of the URL will continue to work but use this new implementation for new integration.

The Single Integration API provides parameters that can be used to create an URL that returns a complete HTML page containing for example an embedded Qlik Sense visualization. This URL can be embedded in a web page, for example by including it in an iframe.

Use the Single configurator to quickly get started using the Single Integration API.

Base URL

The Base URL is constant and defines the location of the machine.

Syntax: Base URL

http[s]://<machinename | servername>/{virtual proxy}/single/?

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.

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( "/single" ) + 1 );

Legacy implementation of the base URL

Before version 3.1, the base URL had a slightly different syntax.

Syntax: Base URL

http[s]://<machinename | servername>/{virtual proxy}/single?

Additional parameters

The following parameters can be used to display a single visualization, a single sheet, or a single snapshot.

Parameter Description
appid

Defining the id of a Qlik Sense app. If no appid is available, the file name will be listed.

Example: appid example

appid=133dab5d-8f56-4d40-b3e0-a6b401391bde

Example: appid example in Qlik Sense Desktop

appid=<FolderPath>%5CHelpdesk%20Management.qvf

obj

Defining the id of a Qlik Sense visualization.

Example:  

&obj=hRZaKk

sheet

Defining the id of a sheet in a Qlik Sense app.

Example:  

&sheet=1ff88551-9c4d-41e0-b790-37f4c11d3df8

snapshot

Defining the id of a snapshot in a Qlik Sense app. Introduced in Qlik Sense version 1.1.

Example:  

&snapshot=EwrnQf

identity

Defining a session identity. If no identity is defined, the session and selection state will be shared with the client.

If an identity is defined, a separate session is created and any selections made in the single feature does not affect a concurrent session in the Qlik Sense client.

lang

Override default language settings by defining the language for the specific object. Supported languages are:

  • Default language: This option does not add any language settings to the URL. The default language will be used.
  • German:

    short: de

    long: de-DE

  • English:

    short: en

    long: en-US

  • Spanish:

    short: es

    long: es-ES

  • French:

    short: fr

    long: fr-FR

  • Italian:

    short: it

    long: it-IT

  • Japanese:

    short: ja

    long: ja-JP

  • Korean: (introduced in Qlik Sense version 3.0)

    short: ko

    long: ko-KR

  • Dutch:

    short: nl

    long: nl-NL

  • Polish: (introduced in Qlik Sense version 3.0)

    short: pl

    long: pl-PL

  • Brazilian Portuguese:

    short: pt

    long: pt-BR

  • Russian:

    short: ru

    long: ru-RU

  • Swedish:

    short: sv

    long: sv-SE

  • Turkish: (introduced in Qlik Sense version 3.0)

    short: tr

    long: tr-TR

  • Simplified Chinese:

    short: Do not use!

    long: zh-CN

  • Traditional Chinese: (introduced in Qlik Sense version 3.0)

    short: Do not use!

    long: zh-TW

Examples:  

&lang=es

&lang=es-ES

opt

Defining options. Supported options are:

  • currsel: displays the Selection bar.
  • debug: starts a JavaScript debugger.

    The debug option can only be defined in the URL.

  • noAnimate: turns off animations.

  • noselections: turns off selections.
  • noInteraction: turns off interaction.

If you want to define multiple options you separate them with a comma sign.

Example:  

&opt=currsel

callback

Registering callbacks. Introduced in Qlik Sense version 1.1.

This is the package name for callback functions.

Use 'test' for testing and use 'external' for integration based on Internet Explorer web component.

The callback parameter is not supported for sheets.

See: Callback reference

bookmark

Defining the id of a bookmark in a Qlik Sense app.

Introduced in Qlik Sense version 1.1.

This is the id of the bookmark to apply.

Example: Bookmark applied

&bookmark=PzsxuKb

select

Field name and values to select.

Introduced in Qlik Sense version 1.1.

The field name and the values define the selections to make. It is possible to define multiple select parameters.

Example: Selections in two fields

&select=Month,1,2,3,4&select=Priority,High

The example above selects the months of January, February, March and April and High priority.

You have to define the number for numeric fields (Month in the example above), text will not work.

Example: Clear all selections

&select=clearall

Example: Clear all selections and then make a new selection

&select=clearall&select=Year,2011

Callback reference

Use callbacks when you use the single feature as an embedded component in, for example, a .NET environment. Callbacks are called if a callback package is defined as a parameter in the URL.

The callback parameter is not supported for sheets.

The following callbacks are defined

  • window[callback package]onError: called when an error occurs. Default is to use a JavaScript alert for errors.
  • window[callback package]onValid: called when an object receives valid data from Qlik engine.
  • window[callback package]onRendered: called when an object is rendered.

Execution order

The execution order of rendering a HTML page containing the object and its set options is as follows:

  1. Clear existing selections (if applicable).
  2. Apply a bookmark (if applicable).
  3. Make selections in fields (if applicable).