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
FirstPulseMetricSizeKnown
eventPulseUrlChanged
eventPulseTimeDimensionChanged
eventPulseFiltersChanged
eventPulseInsightDiscovered
eventPulseError
eventThe 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. |
Get the TableauPulse
object.
addEventListener()
method on the TableauPulse
object.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.FirstInteractive
eventIn 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
};
TableauPulse
object.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);
The following section shows how you could add event listeners to embedded Pulse metrics to gather information or to take further action.
FirstPulseMetricSizeKnown
eventYou 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`;
});
PulseUrlChanged
eventWhen 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)
});
PulseTimeDimensionChanged
eventYou 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);
});
PulseFiltersChanged
eventYou 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);
});
PulseInsightDiscovered
eventYou 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);
});
PulseError
eventYou 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);
});