Dashboard Widget

When embedded in an application, the Dashboard widget enables complete dashboard management for tenant end users.

Quick Embed Sample (For Testing Only)

Important: This example is for testing purposes only.

• In production, you must use a qvToken instead of exposing an apiKey in the UI.
• The apiKey is private and should only be used for communication between backends.
• For testing, clientId can match the userId. In production, the clientId requires a unique identifier for each tenant end user.

<!-- Tag -->
<qrvey-dashboard settings="dashboardConfig"></qrvey-dashboard>

<!-- Config -->
<script>
var dashboardConfig = {   
   "apiKey": "<YOUR_PRIVATE_API_KEY>",   // Testing only. Do not use in production UI.
   "domain": "<DOMAIN>",   
   "appId":  "<APP_ID>", 
   "userId": "<USER_ID>",
   "dashboardId": "<DASHBOARD_ID>",
   "clientId": "<CLIENT_ID>",            // Optional, for testing, this can match userId.
   "orgId": "org:0"                      // Optional, for testing, use org:0 (base organization)
};  
</script>

<!-- Launcher -->
<script type="module" src="https://<DOMAIN>/qrvey-dashboard/qrvey-dashboard/qrvey-dashboard.esm.js"></script>

Production Deployment

• Use qvToken instead of apiKey.
• Pass sensitive values (appId, userId, clientId, orgId) using the qvToken and not in a plain configuration.
• In production, configure roles, orgs, filters, i18n, and theme as needed.

Configuration Object

Property	Type	Required	QVToken Support	Description
domain	String	Yes	No	Qrvey instance URL.
qvToken	String	No	No	Encrypted string securing the widget configuration. Required if no apiKey is provided. This string cannot be used with apiKey.
apiKey	String	No	No	Secret identification token for accessing the application. Required if qvToken is not provided. This string cannot be used with qvToken.
appId	String	Yes	Yes	ID of the Qrvey application. Must be passed using qvToken in production.
userId	String	No	Yes	User ID of the application owner. Must be passed using qvToken in production.
dashboardId	String	No	Yes	ID of a specific dashboard to embed. If omitted, the widget displays the "browse dashboards" page.
clientId	String	No	Yes. Must be passed using qvToken during production.	Unique identifier for the tenant end user. - Used for testing. This can match the userId. - In production, each tenant requires a unique value that is passed using qvToken. If omitted, the widget assumes anonymous.
roles	Array(String)	No	Only	Used for Column Level Security.
orgId	String	No	Yes	Organization ID for the end user. Used for asset ownership. If omitted, the widget uses the clientId's orgId (if set in orgs object). Otherwise, it uses anonymous.
orgs	Array(Object)	No	Only	In a dashboard sharing model, organizations, roles, and users are passed through this object. For more information, see Orgs Object.
userFilters	Object	No	Yes	Collection of custom filters that the system applies to the visualized data. For more information, see Filters in Widgets.
timezone	String	No	Yes	Timezone offset applied to dates. For more information, see Configuring Time Zone Settings.
i18n	Object	No	No	Defines language and localization. For more information, see i18n Object.
themeId	String	No	No	Theme ID to use in the component. For more information, see Accessing a Theme Programmatically.
styles	JSON	No	No	Key-value JSON with style variables. For more information, see Dashboard Styles.
defaultMode	"design" or "interact"	No	No	Sets the dashboard's default mode to open in design or interact mode. Defaults to interact mode. Only applies to a single dashboard.
customTokens	Custom tokens	No	No	Sets custom tokens. For more information, see Using Custom Tokens.
permissions	JSON	No	Only	Record-Level Security permissions object.
asset_permissions	Asset permissions	No	Only	The asset permissions object.
email	String	No	Only	Email of the clientId user. Required to enable scheduling and subscription. Pass this property in the qvToken.
customization	JSON	No	No	The Dashboard customization object.

Orgs Object

The orgs object determines the list of roles, users, and customer organizations available in the dashboard sharing modal. When defined in the orgs object, sharing settings are displayed in the Sharing modal of an embedded dashboard. For more information, see Share Dashboards in Embedded Scenarios.

Property	Type	Description
orgId	String	ID of the organization for which roles and users are defined.
users	Array(Object)	List of users in the organization. Each user is defined by clientId and email.
users.clientId	String	Client ID of the user.
users.email	String	Email address of the user.

Example

"orgs": [
  {
    "orgId": "org:1",
    "orgRoles": ["role1", "role2"],
    "users": [
      { "clientId": "client1", "email": "client1@qrvey.com" },
      { "clientId": "client2", "email": "client2@qrvey.com" }
    ]
  },
  {
    "orgId": "org:2",
    "orgRoles": ["role3", "role4"]
  }
]

i18n

For more information, see Internationalization, Step by Step.

Property	Type	Required	Value
lang	String	Yes	Language to use for the UI (examples: "es", "es-ES").
locale	String	No	Locale code to use for date and number formatting (for example, "es-ES").
currencyFormatOverride	String	No	Accepts currency codes and sets the currency (for example, "EUR") on visualizations and their exports. It overrides the default currency format in the application. Supports the list of ISO 4217 currency codes.

Note: When applied directly to a column in a chart using the Values Format option, the currency setting supersedes the currency setting in currencyFormatOverride.

Example Configuration

The following code block adds an i18n object to the dashboard widget configuration that includes an override for the default currency format.

var config = {  
  "domain": "<DOMAIN>",  
  "qvToken: "<QVTOKEN>",      
  "i18n": {
    "lang": "en",
    "locale":"EN",
    "currencyFormatOverride":"EUR"
  }
}

Note: The i18n object is supported only in the widget configuration object. It cannot be passed in a JWT.

Styles

The Dashboard Widget supports customization through CSS variables, allowing you to adapt the look and feel of dashboards to match your application’s design system. This includes control over fonts, colors, spacing, and other UI elements.

By overriding the available style variables, you can achieve a fully branded experience for end users without altering functionality. This is the recommended way to ensure consistency across embedded dashboards.

For the complete list of available style variables and examples of how to use them, see Styles.

Methods and Events

The Dashboard widget supports the following interaction patterns:

• Direct Method Calls - Uses the executeAction method.
• Event-Based Communication - Uses custom events with promise-based responses.

Both approaches provide the same functionality with different implementation styles. They allow developers to programmatically control dashboard behavior (such as applying filters, switching versions, or triggering downloads) from their host application and integrate dashboard actions into their own UI workflows or automation scripts.

For the complete list of available style variables and examples of how to use them, see Methods and Events.