Widget Embedding Overview
Embedding Qrvey widgets speeds up delivery and keeps your product focused on core values while offering rich analytics, reporting, and automation capabilities. With a small HTML element, a JSON configuration, 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
The Qrvey widget is a pre-built, customizable UI component that consists of UI/UX tied to back-end API endpoints that performs many different functions and can be plugged into your core applications. You can customize widgets by turning features on and off, changing colors and fonts, and tailoring widget 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 Qrvey widgets.
| Widget | Description |
|---|---|
| Dashboard | Embed a complete dashboard so users can build, modify, share, and subscribe to dashboards. Users can also modify charts and other controls included in the dashboard. Use this widget to provide full dashboard management inside your application. |
| Automation | Allows users to create workflows such as data threshold alerts or scheduled tasks. Workflows are back-end processes. This widget helps non-developers to configure automated behavior. |
| Pixel-Perfect Reports | Ideal for multi-page, layout-sensitive PDF exports like invoices or formatted client reports. You can embed this widget in authoring mode to help users design reports, or embed in run mode for exporting. |
| Analysis Suite | Allows quick analysis of an individual dataset. It offers multiple analysis views: - metric view - custom view - tabular grid for filtering and aggregates - summary charts for column-level insights. |
| Download Manager | Allows users to manage scheduled exports and subscriptions. Users can edit or remove schedules, while administrators can view all schedules for the application. |
| Single Panel | Allows embedding of a single chart or panel (for example, stock levels by product line) in place of a full dashboard. |
Core Components of Embedded Widgets
Each page in Composer that supports embedded widgets displays the embed code icon </>. Select the icon to display the code you need to embed the widget:
- HTML element — A special tag included on the page. It contains a
configattribute that uses a JSON configuration object as its value. - Widget config — A JSON object that controls the widget display. Use this element to pass common configuration options, as well as additional properties specific to the widget.
- JavaScript launchers — One or more JavaScript entries 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 | Description |
|---|---|
| api_key | Required for authentication when embedding. |
| app_id | Identifies the Qrvey application that contains the content you want to embed. |
| domain | Tells the widget where to make backend calls and construct URLs. |
| user_id | Identifies the Composer user who created the Qrvey application. |
| qrveyid | ID of the dataset being used. |
Checklist
- Prepare a config JSON with an API key, application ID, user ID, domain, and any other properties that you need to configure for your widget.
- Decide which mode to use: build mode (design) or run mode (preview).
- Test with a development API key and verify the behavior before enabling your widget to the end users.
Best Practices
- Keep secrets out of client code. For more information, see Widget Authentication.
- Limit the embedded UI to match user access permissions. Use the configuration object to toggle features rather than expose everything.
- Use the single panel widget for focused visualizations. Use the dashboard widget for full-feature experiences.
- For printable documents, embed Pixel-Perfect Reports in run (preview) mode to let users export PDFs directly.
- Use the Download Manager to access subscriptions and schedules so users can self-manage exports.
- Document your configuration settings for reference by engineers and product owners to ensure consistent reuse across your pages.