Widget Embedding Overview
Embedding Qrvey widgets speeds up delivery and keeps your product focused on core value while offering rich analytics, reporting, and automation capabilities. By means of a small HTML element, a JSON config, and a launcher script, you can add dashboards, analysis tools, scheduled exports, and more, with configurable security and UI controls tailored to your users.
Overview
A Qrvey widget is a pre-built UI component you can plug directly into your application to deliver powerful analytics and reporting capabilities without rebuilding complex interfaces from scratch. You can customize widges by toggling features on and off, changing colors and fonts, and tailoring behavior to match your product’s look and security needs.
Widget Embedding Tutorial
Tags: Widgets, Embedding
Supported Widget Types
The following table describes supported types of embeddable widgets.
| Widget | Description |
|---|---|
| Dashboard widget | Embed a complete dashboard experience so users can build, modify, share, and subscribe to dashboards, charts, and controls. Use this when you want to provide full dashboard management inside your app. |
| Automations widget | Provide a UI for users to create workflows and back-end processes such as data threshold alerts or scheduled tasks. Good for letting non-developers configure automated behavior. |
| Pixel perfect report widget | Ideal for multi-page, layout-sensitive PDF exports like invoices or formatted client reports. You can embed it in authoring mode to let users design reports or in run mode for exporting. |
| Datasets widget | Allow users to create, manage, and inspect datasets within your product. Useful for self-serve data upload and preparation workflows. |
| Analysis suite widget | Offers multiple analysis views for a single dataset: metric view, custom view, tabular grid for filtering and aggregates, and summary charts for column-level insights. Embed this when you want fast, interactive analysis without exposing full chart editing. |
| Download Manager | Manage scheduled exports and subscriptions. Users can edit or remove schedules; admins can see all schedules for the application. |
| Single panel widget | Embed a single chart or panel (for example, stock levels by product line) when a full dashboard is unnecessary. |
Core Components of Embedded Widgets
Each embedded Qrvey widget includes the following parts:
- HTML element — A special tag included on the page. It always has a config attribute whose value is a JSON configuration object.
- Widget config — A JSON object that tells the widget what to show and how. This is where you pass your API key, target application, domain, security settings, and UI toggles.
- JavaScript launchers — One or more JavaScript files that process the HTML element and render the interactive components in the browser.
Common Configuration Options
The following table describes frequently used configuration options for embedded widgets.
| Option | Purpose |
|---|---|
| apiKey | Required for authentication when embedding. |
| applicationId | Identifies the Qrvey application that contains the content you want to embed. |
| domain | Tells the widget where to make backend calls and construct URLs. |
| UI toggles | Turn parts of the interface on or off depending on user role or product flow. |
| Record-level security | Restrict which records a user can see. |
| Column-level security | Hide or mask sensitive columns. |
| Role-based options | Tailor features and access by role inside the config object. |
Quick Embed Checklist
- Review the code to be embedded and identify the HTML element and launcher scripts.
- Prepare a config JSON with an API key, application ID, domain, and any UI and security flags.
- Decide which mode to use: build mode (authoring) or run mode (execution/export).
- Include the launcher scripts in the page so they can replace the HTML element with the widget UI.
- Test with a development API key and verify behavior for record and column security.
Best Practices
- Keep secrets out of client code. Use server-side token exchange or short-lived keys when possible.
- Limit the embedded UI to match user roles. Use the config object to toggle features rather than exposing everything.
- Use the single panel widget for focused visualizations and the dashboard widget for full-feature experiences.
- For printable documents, embed pixel-perfect reports in run mode to let users export PDFs directly.
- Use the Download Manager for subscription and scheduling workflows so users can self-manage exports.
- Document the config schema you use internally so engineers and product owners can reuse consistent settings across pages.