Skip to main content
Version: 9.3

Custom Events

As a software developer, you can set up Qrvey widgets to emit custom events that trigger actions within a host application.

Dashboard widgets support the following custom events. For more information about events supported by the Dashboard widget, see Dashboard Methods and Events.

Dashboard Loaded Event​

The Dashboard Loaded event qvDSHPageLoaded is emitted when the dashboard is loaded (and the “loading” spinner is no longer displayed) in the Dashboard widgets.

const event = new CustomEvent('qvDSHPageLoaded');

document.addEventListener(“qvDSHPageLoaded”, () => { 
    // Do Something
});

document.dispatchEvent(event);

Items Loaded Event​

The Items Loaded event qvDSHItemsLoaded is emitted when all charts in the viewable area have rendered (and their corresponding “loading” spinners are no longer displayed) in the Dashboard widgets.

const event = new CustomEvent('qvDSHItemsLoaded');

document.addEventListener(“qvDSHItemsLoaded”, () => { 
    // Do Something
});

document.dispatchEvent(event);

JWT Expiration Event: qvTokenExpired​

The qvTokenExpired event is dispatched by embedded Qrvey widgets when the system detects that the authentication token (qvToken) has expired (HTTP status 401).

When It Occurs​

Triggered automatically by the widget when a qvToken is invalid or expired in a dashboard or legacy dashboard.

What It Does​

The widget dispatches a global event in the host application called qvTokenExpired. The event payload contains a detail object with the source widget that triggered the event:

{
  "trigger": "Dashboard Widget - Interaction Mode" // Design Mode, Preview Mode
}

Purpose​

This event enables host applications embedding Qrvey widgets to react to expired tokens in a controlled way.

Common implementation approaches include, but are not restricted to, refreshing the token silently or prompting the user to confirm they are still active.

Typical Use Cases​

  • Refreshing the token by requesting a new qvToken from the back end.
  • Prompting the user with a modal (“Your session expired, select continue to refresh”).
  • Notification that the user session has expired for a given widget (dashboard, report, and so on).

Example Usage​

document.addEventListener('qvTokenExpired', (event) => {
  console.log('Event captured:', event.detail);

  if (event.detail.trigger === 'Dashboard View Widget') {
    // Example: Show a custom modal to the user
    showSessionExpiredModal(() => {
      // Callback: regenerate qvToken and reinitialize the widget
      regenerateTokenAndReloadWidget();
    });
  }
});