Version: 9.2

Single Panel Widget

Embedding a Qrvey single panel widget is a simple way to surface a Qrvey chart inside your application.

Overview

A single panel widget is a lightweight container that displays one chart. This is ideal for displaying a single key metric or visual, such as a quarter-over-quarter sales bar chart, without embedding an entire Qrvey dashboard.

An embedded single-panel widget requires the following items:

Widget configuration object (JSON) so the launcher knows what to render.
An an-panel HTML element that receives the configuration.
Widget properties added to the configuration.
Javascript launcher scripts to parse the configuration and render the chart.

The panel supports common interactions such as filtering and exports of the individual chart, while remaining separate from a full dashboard interface.

The following tutorial video shows how to embed a single Qrvey chart panel and render it securely.

Tags: Widget, Chart, Security

Before You Begin

You need the following information to embed a single panel widget.

Qrvey dataset ID (qrveyid).
Chart ID of the specific chart to embed.
JWT token generated by your back end that securely contains sensitive values (api_key, app_id, user_id).
Panel HTML element.
Qrvey JavaScript widget launchers to include in your front end.

Step 1: Get the Embed Snippet

From the dataset that was used to create your chart, open the Analyze tab, and then select Custom View.
Select the chart and use the Embed Chart link from the chart’s three-dot menu to copy the example configuration, the panel element, and the launcher scripts. Your snippet should include all three.

Step 2: Move Sensitive Properties to Your Back-End Service

The widget configuration properties and their values are visible to anyone who can inspect the front-end browser code. Do not expose sensitive keys in the browser. Move the following properties to a secure back-end service that produces an encrypted JWT:

api_key
app_id
user_id

After your back-end service returns a short-lived JWT token, the front end needs to fetch this token and include it in the widget configuration under the qvToken property.

Step 3: Add the Panel Configuration to the Front End

Keep non-sensitive fields in the public configuration. Typical properties for the single panel widget include:

Property	Details
qrveyid	Dataset ID (source dataset for the chart).
type	Either `chart` or `metric`.
chart_id	ID of the chart being embedded.
featurePermission	Optional object to disable features not supported in single panel mode.

Note: If you are not passing a clientId in your widget configuration, it is not necessary to include the featurePermission object. By default, the subscriptions feature is not available. If you are passing a clientId, it is recommended to hide the Subscribe option in the Qrvey interface, because this feature is not supported in the single panel widget.

Example Configuration

const qrveyPanelConfig = {
  "domain": "your-domain.qrvey.com",
  "qrveyid": "DATASET_ID",
  "type": "CHART",
  "chart_id": "CHART_ID",
  "featurePermission": {
    "hideSubscription": true
  },
  "qvToken": "QV_TOKEN"
  };

Add the required Qrvey launcher scripts to your page, preferably just before the closing body tag. These scripts read the configuration file and render the chart inside the panel element.

<script src="https://cdn.qrvey.com/widgets/launcher-1.js"></script>
<script src="https://cdn.qrvey.com/widgets/launcher-2.js"></script>

Step 5: Create the an-panel Element and Set the Configuration Attribute

The panel element accepts a config attribute. Create it dynamically and append it to a container element in your page. The following example shows the logic in JavaScript; run this in a script block or your front-end code.

Complete Example

async function embedWidget() {
  const token = await fetchToken();
  let widgetContainer = document.querySelector("#widget-container");
  window["qrvey-panel-config"] = {
    "domain": "your-domain.qrvey.com",
    "qrveyid": "DATASET_ID",
    "type": "CHART",
    "chart_id": "CHART_ID",
    "featurePermission": {
      "hideSubscription": true
    },
    "qvToken": "QV_TOKEN"
  };
  let dashboard = document.createElement("an-panel");
  dashboard.setAttribute("config", "qrvey-panel-config");
  widgetContainer.append(dashboard);
}

Testing and Expected Behavior

After adding the structures, refresh the page to test the embed. A successfully embedded single panel chart renders without console errors.

Troubleshooting: 401 Unauthorized

If your browser console displays a 401 unauthorized error code when trying to load the panel, the widget does not include valid authentication. Confirm the following:

Your widget configuration object includes the qvToken property.
Your back end returns a valid JWT containing the api_key, app_id, and user_id.
The front end fetches the JWT and sets it in the widget config as qvToken.
The token has not expired.

Best Practices

Do not embed API keys or user IDs in client-side code. Always generate a signed JWT from the server.
Keep JWT lifetimes short and validate their origins on the back end if possible.
Place the launcher script references close to the closing body tag so the DOM is ready when they run.
Test with developer tools open to catch authentication or configuration errors quickly.

Single Panel Widget

Overview