Embed a Dashboard into an External Web Application

You can use Qrvey’s embed options and parameters to tailor the dashboard experience to your specific product design and user requirements.

Overview

Many SaaS applications need to display analytics directly within their own interface rather than redirecting users to a separate platform. Embedding dashboards allows organizations to deliver a seamless analytics experience where users can interact with data without leaving the main application.

This page describes how to embed a Qrvey dashboard securely and how to customize its colors to match your app’s design and user flow.

By the end of this guide, you will be able to:

• Generate and use an embed token for secure access.
• Embed a dashboard into your application.
• Customize colors, fonts, and shapes to match your product experience.

Use Case

A SaaS company can embed Qrvey dashboards into its analytics portal. The portal uses a custom color theme.

When securely embedding the dashboard with the corresponding CSS variables defined, the development team can ensure that all charts, filters, and buttons visually match the portal’s brand guidelines, providing users with a unified experience.

Before You Begin

To embed a dashboard, you should have a working knowledge of HTML, JavaScript, and CSS. In addition, obtain the following items, permissions, and access:

• A dashboard ready to be embedded within an existing application.
• A secure API endpoint to generate the qvToken for authenticated embedding.
• Access to Qrvey Composer with permissions to view and embed dashboards.
• Developer access to your web application’s front-end codebase.

Implementation

1. Retrieve the embed information from a dashboard.

   a. Log into Qrvey Composer.

   b. Open an existing application that contains a dashboard.

   c. Select Embed Dashboard at the top right corner of the dashboard view. A dialog opens, displaying a sample embed code snippet.

   d. The popup provides essential identifiers required to perform a secure embed. Most of these values are required to generate the qvToken used to embed the dashboard security.

   Note: This sample code uses an API key within the configuration object. While useful for testing and identifying the required parameters, it is not secure for production environments.

2. Generate the qvToken (also called Widget Security Token).

   This short-lived, server-generated token is used to securely embed Qrvey widgets. It replaces the static API key, ensuring that only authenticated users can access the embedded content.

   On your backend, create an endpoint that generates a qvToken using Qrvey’s authentication API. This token should be tied to the user session in your parent app to ensure secure access. For more information, see the following pages:

   • Dashboard Widget
   • Qrvey Security Token Authentication

3. Embed the dashboard in your application.

   a. After you have created the qvToken and configuration values, add the Qrvey dashboard widget script to your parent application’s HTML.

   b. Create a container where the dashboard can render.

   c. Initialize the dashboard using the secure embed configuration that includes your qvToken.

   <!-- Tag —->
   <qrvey-dashboard settings="dashboardConfig"></qrvey-dashboard>
   <!-- Config —->
   <script>
   var dashboardConfig = {   
   "qvToken": "<GENERATED_QV_TOKEN>",
   "domain": "<DOMAIN>",
   "dashboardId": "<DASHBOARD_ID>"
   };  
   </script>
   <!-- Launcher —->
   <script type="module" src="https://<DOMAIN>/qrvey-dashboard/qrvey-dashboard/qrvey-dashboard.esm.js">
   </script>

4. Customize the dashboard with CSS variables.

   To align its appearance with your parent application:

   a. Open your app’s main stylesheet.

   b. Locate the dashboard’s custom tag and define the CSS variables to override. For more information, see the CSS Variable Reference.

   Example:

   qrvey-dashboard {
       --qv-global-color-main: blue;
       --qv-global-border-border: 2px;
       --qv-global-font-family: Inter, sans-serif;
   }

   When embedded, the dashboard renders inside a custom HTML tag (for example, <qrvey-dashboard>).

Troubleshooting

The following table displays common issues encountered when embedding custom dashboards and steps used to resolve them.

Issue	Cause	Solution
Tooltips or modals not adopting CSS variables.	Some overlays render outside the dashboard’s custom HTML tag.	Use browser DevTools to inspect the modal or tooltip element. Add its selector to your parent stylesheet with the same variable overrides.
Dashboard fails to load.	Missing or invalid qvToken.	Regenerate a valid qvToken from your backend and confirm the userId and appId values.
Colors not changing.	CSS specificity issue.	Use more specific selectors or ensure the stylesheet loads after the widget script.
Widgets flicker on load.	Slow token or dataset response.	Cache qvToken efficiently or pre-fetch before rendering.

Best Practices

• Use qvToken-based embedding for production environments.
• To apply updates to all embedded environments, store color variables in a shared theme file.
• To ensure consistent rendering, test customizations in multiple browsers.