Embed Tableau Pulse


You can use the Embedding API to embed Tableau Pulse in your web apps and web pages. The Embedding API provides a <tableau-pulse> web component that you can place in your HTML code. If you want to use JavaScript to initialize the API and embed Tableau Pulse, you can instantiate a TableauPulse object and set Tableau Pulse properties. For information about using Tableau Pulse and creating metric definitions, see Create Metrics with Tableau Pulse.

Note

To embed Tableau Pulse metrics in your web page or application, you must configure Tableau and your web application to use connected apps for authentication.

For information about using connected apps, see Authentication and Embedded Views. and Use Tableau Connected Apps for Application Integration.

The following information will help get you started embedding metrics with Tableau Pulse.

In this section

Use the web component to initialize the API and embed Tableau Pulse

The easiest way to initialize the API and embed Tableau Pulse in your web pages is use the new <tableau-pulse> web component in your HTML page. The component looks like the following, where the src attribute specifies the URL to Tableau Pulse metric on Tableau Cloud.


<tableau-pulse id="tableauPulse"
    src='https://online.tableau.com/pulse/site/mysite/metrics/3ec1437f-d40d-4a5d-9363-aa22cd862838'
    height="800"
    width="100%">
</tableau-pulse>

To use the web component, you first need to create a metric with Tableau Pulse. After you create the metric, copy the URL from the address bar. This address is the src URL that you use in the Tableau Pulse web component. The URL takes the following form:

https://[MY_TABLEAU]/pulse/site/[MY_SITE]/metrics/[metric_id]

Where [MY_TABLEAU] and [MY_SITE] are replaced with the name of your Tableau host and site. The last part of the URL identifies the specific metric (the [metric_id]). This corresponds to the metric_id used with the Tableau REST API for the Tableau Pulse endpoints.

When you create the web component, it’s good to specify an unique identifier (id) in case you need to reference the component later.

In your HTML code, add a link to the Embedding API v3 library. In general, it is a best practice to link to the Embedding API library on the Tableau instance that serves the Tableau Pulse metric. For more information, see Access the Embedding API. The Tableau Pulse web component is available on Tableau Cloud 2024.1 and later (starting with version 3.8 of the Embedding API library).

In addition to the src attribute, the <tableau-pulse> web component has additional settings that you can configure. For example, the height and width of the Tableau Pulse metric, and the option to show or hide buttons in the UI. For a list of the options, see Configure TableauPulse objects and components.

The following example uses the <tableau-pulse> web component. The web component specifies the URL of the Tableau Pulse metric and also includes the connected app token that allows the Tableau Pulse metric to be embedded and viewed on the web page.

<script type="module"
  src="https://online.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js">
</script>

<tableau-pulse id="tableauPulse"
    src='https://online.tableau.com/site/mysite/pulse/metrics/3ec1437f-d40d-4a5d-9363-aa22cd862838'
    height="800"
    width="100%"
    token='CAtoken'>
</tableau-pulse>

Use JavaScript to initialize the API and embed Tableau Pulse

In some instances, you might prefer to configure and initialize Tableau Pulse using JavaScript, rather than using the <tableau-pulse> web component. In this case, you use a TableauPulse JavaScript object.

The first step is to create an <div> to contain the Tableau Pulse metric in your HTML code. In this respect, this is similar to what you do to embed a view. You also need to give the <div> an identifier (say, pulseJsContainer) so that you can specify that element when you append the embedded Tableau Pulse metric. This is important because the metric is not rendered until you add it to the DOM.

HTML code

<div id="pulseJsContainer"></div>

In your JavaScript code, you need to import the TableauPulse object from the Embedding API v3 library. You can then create a new instance of the object and configure the object with the path to the metric and other properties by the object (see Configure TableauPulse objects and components). It’s important to note that creating the object new TableauPulse() does not render the Tableau Pulse metric. To do that, you must add it to the DOM (that is, add it to document using appendChild(), for example).

Also, if you put your JavaScript code in a separate .js file, you’ll need to import the file in your HTML page with the type set as module.

<script type="module" src="./myEmbeddedCode.js"></script>

For example, the following code shows how you might embed Tableau Pulse. In this instance, the Explore filter button is not shown.


import {
  TableauPulse
} from 'https://online.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js';

const pulse = new TableauPulse();

pulse.src = 'http://my-server/scope/scoped-123-1';
pulse.token = 'someCAtoken';
pulse.disableExploreFilter = true;

document.getElementById('pulseJsContainer').appendChild(pulse);

Combine JavaScript and the <tableau-pulse> web component to embed the metric

You can take a hybrid approach, that is, combine the simplicity of using HTML web component with the programmatic advantages of JavaScript. In this case, you add a <tableau-pulse> web component to your HTML page. But instead of specifying all of the attributes, the URL and other options, you just specify the <tableau-pulse> element and provide it with a unique id.

In your HTML code, include the link to the Embedding API library and then add the web component.


<script type="module" src="https://online.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js"></script>
   ...

<tableau-pulse id="tableauPulse"></tableau-pulse>
   ...

In your JavaScript code, get the pulse object from the HTML web component, and then use the pulse object to configure the embedded metric. Note that this example uses document.querySelector() to reference the <tableau-pulse> web component. You could also use the document.getElementById() to reference the web component if you had more than one embedded metric on the page.


const pulse = document.querySelector('tableau-pulse');
pulse.src = url;

This is similar to the process you take when you Interact With the View created using the web component.

Configure TableauPulse objects and components

To configure Tableau Pulse, you can use a set of HTML attributes on the <tableau-pulse> web component, or as JavaScript (JS) properties on the corresponding TableauPulse JavaScript objects. For HTML attributes that accept a value, such as width and height, the syntax is <property>="<value>". For Boolean properties, such as disable-explore-filter, you can either include the flag to effectively set it to true, or omit it to effectively set it to false.

The following table lists the properties you can add to the <tableau-pulse> web component, or as JavaScript (JS) properties on the corresponding TableauPulse JavaScript object.

HTML Property JS Property Accepted Values Description Applies to
height TableauPulse.height (e.g. “800px”) Can be any valid CSS size specifier. If not specified, defaults to the published height of the Tableau Pulse metric. <tableau-pulse>, TableauPulse
width TableauPulse.width (e.g. “800px”) Can be any valid CSS size specifier. If not specified, defaults to the published width of the Tableau Pulse metric. <tableau-Pulse>, TableauPulse
disable-explore-filter TableauPulse.disableExploreFilter boolean Indicates whether to hide Explore Filters button. If not specified, defaults to false (the button is shown). <tableau-pulse>, TableauPulse
layout TableauPulse.layout HTML: "card", "ban", "default" – JS Properties: PulseLayout.Card, PulseLayout.Ban, PulseLayout.Default Specifies the layout of the embedded Tableau Pulse metric. The default setting is to embed the full Pulse metric, that is, all the components of the Pulse metric that appear on Tableau, including filters and AI Insights. The PulseLayout.Card layout only embeds the essential components, the title, the KPI, the trend, and comparison. The PulseLayout.Ban layout shows only the KPI (big aggregated number). <tableau-pulse>, TableauPulse
token TableauPulse.token JSON web token (JWT) The JWT is used when the Tableau Pulse is configured to use a connected app or for EAS on Tableau Server. Use the scope tableau:insights:embed when you generate the JWT. <tableau-pulse>, TableauPulse

Note: When adding properties to the <tableau-pulse> component, use the HTML Property name. Use the JS Property names for the TableauPulse object.

Control layout of the embedded Pulse metric

Tableau Pulse can provide a lot of information and insights about your data metrics. However, when you embed the Pulse in a web page or application, you might only want to show a portion of those insights so that you can customize the content for your customers. Using the layout attribute of the Tableau Pulse web component, you can control what you information you embed.

By default, if you do not specify the layout, the entire Pulse metric is embedded. This includes the filters and AI Insights, and other components. If you only want to embed the title, the KPI, the trends, and the comparison, you can specify layout="card" attribute in the web component, or PulseLayout.Card if you are using JavaScript.

HTML


<tableau-pulse id="tableauPulse"
    src='https://online.tableau.com/pulse/site/mysite/metrics/3ec1437f-d40d-4a5d-9363-aa22cd862838'
    layout="card" token="someCAToken">
</tableau-pulse>

JavaScript

Note: be sure to import the PulseLayout class.


import {
  TableauPulse, PulseLayout,
} from 'https://online.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js';

const pulse = new TableauPulse();

pulse.src = 'https://online.tableau.com/pulse/site/mysite/metrics/3ec1437f-d40d-4a5d-9363-aa22cd862838';
pulse.token = 'someCAtoken';
pulse.layout = PulseLayout.Card; 

document.getElementById('pulseJsContainer').appendChild(pulse);

The following is an example of what a Pulse metric looks like when you specify the card layout.

Example of the card layout

Display the KPI

If you want to embed the minimum number of Pulse components, in this case the title and the KPI (sometimes referred to as the big aggregated number), you can specify layout="ban" attribute in the web component, or PulseLayout.Ban if you are using JavaScript.

The following is an example of what am embedded Pulse metric looks like when you specify the ban layout.

Example of the card layout

Authentication and permissions

The Embedding API provides options for authentication, however, if you are embedding Tableau Pulse from Tableau Cloud, you must configure Tableau to use a connected app for authentication. For information about using connected apps, see Authentication and Embedded Views. The scope (scp) to use for the Tableau Pulse is tableau:insights:embed. You need to know the scope when you generate the JSON web token (JWT) that is associated with the <tableau-pulse> component or TableauPulse object.

Note: When you embed Tableau Pulse, and intend to share the Tableau Pulse with a large number of people, it's a best practice for users to have Viewer permissions. If not, you might expose the Tableau Pulse for editing by anyone who views the embedded Tableau Pulse page. Be aware of the permissions of your intended users. Explorer and Creators have the capacity to edit Tableau Pulse definition.

It's also a good practice to limit access to Tableau content by restricting the connected app to a single project, and that the project should contain only content you are comfortable exposing through that connected app.

For more information about connected apps, see Use Tableau Connected Apps for Application Integration.

What’s next