Add Event Listeners to Tableau Pulse


You can use event listeners to create actions based on events that happen with the Tableau Pulse metric. When users make changes to filters, time dimensions, or when they discover new insights, you could use these events to gather information about the current state of the metric. Using this knowledge, you could add new interactions and make changes to your embedded application to suit the needs of your users.

In this section


Supported Tableau Pulse events

The Embedding API supports the JavaScript addEventListener() method. You can register event listeners for Tableau Pulse objects. The Embedding API supports the following event types (TableauEventType) for Tableau Pulse metrics.

TableauEventType String literal Description
FirstInteractive firstinteractive Raised when an embedded Pulse metric has completed its initial rendering and is interactive.
FirstPulseMetricSizeKnown firstpulsemetricsizeknown Raised when the size of the Pulse metric is known.
PulseError pulseerror Raised when an internal Pulse error occurs.
PulseFiltersChanged pulsefilterschanged Raised when a Pulse filter change occurs. See Adding an event listener for a PulseFiltersChanged event.
PulseInsightDiscovered pulseinsightdiscovered Raised when a Pulse insight is discovered.
PulseTimeDimensionChanged pulsetimedimensionchanged Raised when a Pulse time dimension change occurs.
PulseUrlChanged pulseurlchanged Raised when a Pulse URL change occurs. Note that changes to Pulse filters or time dimensions creates a new URL for the Pulse metric with those settings.

Add an event listener using the addEventListener() method

  1. Get the TableauPulse object.

  2. Add the event listener by calling the JavaScript addEventListener() method on the TableauPulse object.
  3. Specify the type of event and the event handler. The type of the event must be one of the supported types defined in the TableauEventType enumeration (see Supported Pulse events). The event handler can either be a callback function or an anonymous inline function. The callback method or inline function can handle the event object raised to retrieve additional data captured in the event.

Example: Adding an event listener for a FirstInteractive event

In some cases you might want to take actions immediately after the Pulse metric first loads. For example, you want to set filters or perform some other customization for those viewing the embedded metric. You can do this by adding an event listener for a TableauEventType.FirstInteractive event. After the Pulse metric has rendered and is interactive, the first interactive event is raised, which calls your event handler. You can use your event handler to call other methods that you want to run after initialization. The following example shows an event handler that uses an inline anonymous function that writes the event to the console.


// assumes a Pulse object has been created

const tableauPulse = document.querySelector("tableau-pulse");

tableauPulse.addEventListener(TableauEventType.FirstInteractive, (e) => {
      console.log(e.type);
      // call methods to run immediately after loading

});

Here’s the same event handler, this time using a callback function.


// assumes a Pulse object has been created 

const tableauPulse = document.querySelector("tableau-pulse");

tableauPulse.addEventListener(TableauEventType.FirstInteractive, firstInteractiveHandler);


function firstInteractiveHandler(e) {
      console.log(e.type);
      // call methods to run immediately after loading
};


Remove an event listener

  1. Get the TableauPulse object.
  2. Remove the event listener by calling the JavaScript removeEventListener() method and specifying the event type and the name of your event handler. For example, to remove the event handler for the TableauEventType.FirstInteractive event called, firstInteractiveHandler you might use something like the following:
 
const tableauPulse = document.querySelector("tableau-pulse");
tableauPulse.removeEventListener(TableauEventType.FirstInteractive, firstInteractiveHandler);


Examples: Tableau Pulse event listeners

The following section shows how you could add event listeners to embedded Pulse metrics to gather information or to take further action.


Adding an event listener for a FirstPulseMetricSizeKnown event

You can add an event listener to watch for the moment the Tableau Pulse metric fully renders, and its dimensions are known.

The following example shows how you might extract the dimensions of the Pulse metric from the event details. Use the dimensions to set the style properties for the Pulse iframe, and to adjust and customize other components in your embedded application.

// assumes a Pulse object has been created named "tableauPulse"

  tableauPulse.addEventListener(TableauEventType.FirstPulseMetricSizeKnown, (e) => {
        console.log(TableauEventType.FirstPulseMetricSizeKnown, e.detail);
        // Extract the width and height from the event details
        const { width, height } = e.detail;
        // Set the width and height properties of the Pulse iframe style
        tableauPulse.iframe.style.width = `${width}px`;
        tableauPulse.iframe.style.height = `${height}px`;
      });


Adding an event listener for a PulseUrlChanged event

When users change filters or change the time dimensions on an embedded Pulse metric, the changes also create a new URL for the metric. You can capture these events using the PulseUrlChanged event. The information returned from the event includes the old URL and the new URL, and also information about the context. Currently, the value returned for context is either undefined or "session-expired", if the Tableau Pulse session has timed out. To ensure a seamless experience for users, you could add an event listener that checks for (context = 'session-expired') and use that information to generate a new JWT to keep users logged in.

// assumes a Pulse object has been created named "tableauPulse"

tableauPulse.addEventListener(TableauEventType.PulseUrlChanged, (e) => {
      console.log(TableauEventType.PulseUrlChanged);
      console.log('oldUrl', e.detail.oldUrl);
      console.log('newUrl', e.detail.newUrl);
      console.log('context', e.detail.context)

});


Adding an event listener for a PulseTimeDimensionChanged event

You can add an event listener to watch for any change to the time dimension in the Pulse metric. When users change the time dimensions on an embedded Pulse metric, the change also creates a new URL for the metric. This event is also raised whenever you call the applyTimeDimensionAsync() method.

// assumes a Pulse object has been created named "tableauPulse"

tableauPulse.addEventListener(TableauEventType.PulseTimeDimensionChanged, (e) => {
      console.log(TableauEventType.PulseTimeDimensionChanged);
      console.log('timeDimension', e.detail.timeDimension);
});


Adding an event listener for a PulseFiltersChanged event

You can add an event listener to watch for any changes to the filters that are applied to the Pulse metric. This includes changes made in the Tableau Pulse user interface, by selecting and applying filter options, or by Embedding API calls to the Pulse filter methods (applyFilterAsync, applyFiltersAsync, clearFilterAsync, clearFiltersAsync.

Note that because applying filters to a Pulse metric creates and navigates to a new metric, it’s best to ensure the new metric has loaded before attempting to interact with it. The easiest way to do this is by adding a one-time event listener for the next TableauEventType.FirstInteractive event and wrapping it in a promise that resolves when the event occurs.

For example, the following code inserts a first interactive event that must resolve before calling the getFiltersAsync method. Note that the event handler for the Pulse filter change event is an anonymous async call and that the two method calls (the addEventListener() promise and the getFiltersAsync()) use the await keyword. The event listener for the first interactive event uses the once option, so that the listener is only invoked at most one time before being removed.

// assumes a Pulse object has been created named "tableauPulse"

tableauPulse.addEventListener(TableauEventType.PulseFiltersChanged, async (e) => {
      console.log(TableauEventType.PulseFiltersChanged);

      await new Promise(resolve => {
      tableauPulse.addEventListener(TableauEventType.FirstInteractive, resolve { once: true });
      });

      const filters = await e.detail.getFiltersAsync();
      console.log('filters', filters);
});


Adding an event listener for a PulseInsightDiscovered event

You can add an event listener to capture the details whenever an insight for a Pulse metric is selected.

The following code example shows how you could extract information from the event details, including the type of insight, the question being asked, markup, and score. For example, you could extract the HTML markup of the insight and use that somewhere else in your embedded application. For more information about the insights, see The Insights Platform and Insight Types in Tableau Pulse.

// assumes a Pulse object has been created named "tableauPulse"

tableauPulse.addEventListener(TableauEventType.PulseInsightDiscovered, (e) => {
      console.log(TableauEventType.PulseInsightDiscovered);
      console.log('id', e.detail.id);
      console.log('characterization', e.detail.characterization);
      console.log('markup', e.detail.markup);
      console.log('question', e.detail.question);
      console.log('score', e.detail.score);
      console.log('type', e.detail.type);
      console.log('version', e.detail.version);
});


Adding an event listener for a PulseError event

You can add an event listener to capture the details when a Pulse error occurs.

The following code example shows the breakdown of the event details.

// assumes a Pulse object has been created named "tableauPulse"

tableauPulse.addEventListener(TableauEventType.PulseError, (e) => {
      console.log(TableauEventType.PulseError);
      console.log('message', e.detail.message);
      console.log('httpStatus', e.detail.httpStatus);
      console.log('messageVisibility', e.detail.messageVisibility);
});