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.

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
• Use JavaScript to initialize the API and embed Tableau Pulse
• Combine JavaScript and the <tableau-pulse> web component to embed the metric
• Configure TableauPulse objects and components
• Authentication and permissions
• What’s next

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 Export 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.

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.

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

What’s next

• For information about using Tableau Pulse and creating metric definitions, see Create Metrics with Tableau Pulse.

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