Tableau Embedding API v3 replaces the previous versions of the Tableau JavaScript API used for embedding Tableau in web pages and applications. The Embedding API v3 provides new enhancements to facilitate your embedding scenarios.
This document describes the differences in the APIs and what steps you can take to upgrade and migrate existing solutions to the Embedding API v3.
In this section
The Tableau Embedding API v3 provides a redesigned experience for embedding. The Embedding API v3 is the third iteration of the Tableau JavaScript embedding solution and has been modernized to take on new functionality. If you are unfamiliar with the previous embedding solution, JavaScript API v2, you can read the Tableau JavaScript API documentation. Like the JavaScript API v2, the Embedding API v3 is used to embed Tableau in web pages and applications and to add interactivity and customization.
If you’ve ever used the Embed Code (available in the Share dialog box), you’ve likely used the JavaScript API v1. The JavaScript API v1 was used for all the Embed Code prior to Tableau 2022.3. The Tableau JavaScript v1 was used primarily (or solely) in the Embed Code available in the Share dialog box of Tableau Server, Tableau Cloud (and is still used on Tableau Public).
The Embedding API v3 is similar to the JavaScript API v2 in some respects, but it uses a slightly different syntax. But the biggest difference is the initialization of the viz, the Embedding API v3 uses web components. Web components are a standard available in all modern browsers, and allow you to add custom, and 3rd party, functionality to your web page using HTML syntax as easily as adding an <image>, <link>, or <div>. Using the web component technology, we have created <tableau-viz> and <tableau-authoring-viz> components that you can use to add visualizations to your web pages.
Another change from the previous JavaScript libraries is that the Embedding API v3 library is a JavaScript ES6 module. To include the v3 library in the HTML code for your web application, you need to set the type attribute to module in the <script> tags. For more information about the use of modules, see JavaScript modules.
Note: The term Embed Code in this documentation, refers to the code copied to the clipboard when you click the Copy Embed Code button in the Share dialog box. This code allows you to embed a view into another web page.
If you used the Embed Code to embed Tableau views, note the following. The Embed Code in Tableau Server (prior to version 2022.3) and Tableau Cloud (prior to October 2022), used an earlier version of the Tableau JavaScript library (v1). The JavaScript API v1 has been around since Tableau 8.0. More than 10 years ago. We recommend replacing the old code with the new Embed Code (in Tableau 2022.3 and later, and current Tableau Cloud), which uses the Embedding API v3. For more information, see Replace the “Embed Code” from previous versions.
If you are starting a new embedding project, use the Embedding API v3.
For existing JavaScript API v2 projects, we recommend migrating your code as your timeline allows, because the Embedding API v3 can enable more robust embedding and because we will eventually end support for the JavaScript API v2.
Previous versions of Tableau Server and Tableau Cloud used the Tableau JavaScript API v1 for the Embed Code. Note that Tableau Public still uses this older code. The code looks similar to the following, although the order and type of the elements might differ. Notice that the src file referenced is viz_v1.js, the Tableau JavaScript v1 library.
<script type='text/javascript' src='https://myserver/javascripts/api/viz_v1.js'></script>
<div class='tableauPlaceholder' style='width: 1500px; height: 827px;'>
<object class='tableauViz' width='1500' height='827' style='display:none;'>
<param name='host_url' value='https%3A%2F%2Fmyserver' />
<param name='embed_code_version' value='3' />
<param name='site_root' value='/t/Superstore' />
<param name='name' value='MyView' />
<param name='tabs' value='no' /><param name='toolbar' value='yes' />
<param name='showAppBanner' value='false' /></object>
</div>
To update an embedded viz from the JavaScript API v1 to the new Embedding API v3, your best option is to replace the v1 Embed Code with the Embed Code from Tableau Cloud or Tableau Server 2022.3 or later. That is, use a recent version of Tableau to navigate to the viz and then open the Share dialog box and click Copy Embed Code.
The Embedding API v3 code looks something like the following:
<script type='module' src='https://example.com/javascripts/api/tableau.embedding.3.latest.min.js'></script>
<tableau-viz id='tableau-viz'
src='https://example.com/t/site/views/my-workbook/my-view'
width='1328' height='683' toolbar='bottom' >
</tableau-viz>
The v3 Embed Code is just as easy to copy and paste into your HTML code as the v1 is, and it appears simpler because of the <tableau-viz> web component. Notice also that you can customize the properties of the embedded viz without nesting <param> elements. For information about customizing the viz, see Configure Embedding Objects and Components.
Another advantage to using the latest version of the Embed Code is how easy it is to go from a simple scenario, where you just use the Embed Code, to one where you interact with the viz using the Embedding API v3 API. You can get started with the API simply by pasting in the v3 version of the Embed Code and then start layering on interactions and event listeners. For information, see Basic Embedding and Interact with the View.
Let’s take a closer look at the key parts of initializing an embedded viz using the Embedding API v3 and compare that to the JavaScript API v2.
The following section describes some of the differences in using the Embedding API v3. Note that in the examples we mostly refer to the <tableau-viz> web component, but the principals apply to <tableau-authoring-viz> and other components Tableau provides.
The way you access the Embedding API v3 library is similar to the way you access the library in JavaScript v1 and v2. You simply include the correct library .js file from the host serving the viz. As before, you can reference the .js from your on-premise Tableau Server, from Tableau Cloud, or from Tableau Public. In addition, you can also get the v3 library from a CDN (https://embedding.tableauusercontent.com/).
Note that Embedding API v3 library is an ES6 module. You’ll need to import the Embedding API v3 objects and classes you need in your JavaScript code. In the HTML code for your web application, you’ll need to import the library or your JavaScript files with the type attribute set to module in the <script> tags. For more information about linking to specific versions of the library, see Access the Embedding API.
For example, the following shows how you might import the Embedding API library into your JavaScript file from an Tableau Cloud pod. This example imports the TableauViz object and the TableauEventType elements.
import {
TableauViz,
TableauEventType,
} from 'https://10ax./javascripts/api/tableau.embedding.3.latest.min.js';
The following example, imports your JavaScript file into your HTML code.
<script type="module" src="./myEmbeddedCode.js"></script>
For more information about importing the library, see Basic Embedding.
The process of initializing the Embedding API v3 is different from how you initialized the JavaScript API v2. In v3, you have a more options to choose from, giving you some flexibility in your code. In this section we will compare the v3 initialization with v2.
In the JavaScript API v2, you initialized the viz by adding an empty <div> object to your HTML code and then creating a new tableau.Viz object, referencing the <div> and the viz url. For example, if you were using JavaScript v2 your HTML code might include the following:
<div id='tableauViz'></div>
You initialized the v2 API in your JavaScript code with a call to tableau.Viz() method. For example, the following JavaScript v2 code defines the URL for the viz (src=), gets the reference to the <div> that holds the viz ("tableauViz"), and passes those along with an empty set of options to tableau.Viz() method. The new viz object.
let placeholderDiv = document.getElementById("tableauViz");
let src = "http://my-server/views/my-workbook/my-view";
let options = {}
let viz = new tableau.Viz(placeholderDiv, url, options);
In the Embedding API v3, the initialization step is simplified and can happen all inside of your HTML, thanks to the support for Tableau web components. For example, add the <tableau-viz> web component to your HTML code, specify the src URL for your viz and provide an id so you can reference the embedded viz in your JavaScript code as needed.
<tableau-viz id="tableauViz"
src='http://my-server/views/my-workbook/my-view'>
</tableau-viz>
If you need more flexibility, you can also initialize the v3 API in a similar manner to the JavaScript API v2. You do this by calling TableauViz() to create a new viz object. In this case, as with the JavaScript v2, you will need to reference an HTML element and use that to append the embedded viz.
HTML:
<div id="tableauViz"></div>
You need to give the <div> an identifier (say, tableauViz) so that you can specify that element when you
append the embedded view.
In your JavaScript code, you create the viz object, specify the URL of the viz and set other options.
JavaScript:
const viz = new TableauViz();
viz.src = 'https://my-server/views/my-workbook/my-view';
viz.toolbar = 'hidden';
document.getElementById('tableauViz').appendChild(viz);
It’s important to note that creating the object (new TableauViz()) does not render the view. To do that, you must add it to the DOM (that is, add it to document using appendChild(), for example).
For more information, see Use JavaScript to initialize the API and embed the view.
Important notes about the above approach:
You can use JavaScript’s built-in document object to choose where in your HTML code you want to add the viz. The above example uses an empty <div> and getElementById similar to the JavaScript API v2 approach, but you may other approaches depending on your scenario. Read more about JavaScript’s document object.
All of the configuration options listed above as properties of the viz object can be defined in the same manner as viz.toolbar, see Configure Embedding Objects and Components
Changing the properties, as shown in this example, will re-render the viz if it is already rendered. This is especially important to note for filtering. The addFilter method is not intended to be used after the viz has been initialized, instead use applyFilterAsync (and the other Filtering methods when appropriate).
A highly recommended approach is to combine the <tableau-viz> web component with the the programmatic advantages of JavaScript. In this case, you create the web component and then reference that object in your JavaScript.
In your HTML code, include the link to the Embedding API library and then add the web component.
<script type="module" src="https://my-server/javascripts/api/tableau.embedding.3.latest.min.js"></script>
<!-- ... -->
<tableau-viz id="tableauViz"></tableau-viz>
<!-- ... -->
In your JavaScript code, get the viz object from the HTML web component, and then use the viz object to configure the embedded view, add the viz url, toolbar location, etc. Note that this example uses document.querySelector to reference the <tableau-viz> web component.
// Get the viz object from the HTML web component
const viz = document.querySelector('tableau-viz');
viz.src = url;
This is similar to the process you take when you Interact With the View created using the web component.
For more information, see Combine JavaScript and the TableauViz web component to embed the view.
To specify options on how to initialize the viz in the JavaScript API v2, you would add those to the options object that is included in the viz object’s constructor’s arguments. In the Embedding API v3, you can simply add those as properties of the viz component:
<tableau-viz id="tableauViz"
src="http://my-server/views/my-workbook/my-view"
device="phone" toolbar="bottom" hide-tabs>
</tableau-viz>
For information about configuring the viz, see Configure Embedding Objects and Components.
In JavaScript API v2 you can add filtering by specifying a field-value pair in the URL or options object. In the Embedding API v3, you can accomplish the same thing by adding <viz-filter> elements as children to your <tableau-viz> objects. You can also set initial parameter values.
<tableau-viz id="tableauViz"
src="http://my-server/views/my-workbook/my-view"
device="phone" toolbar="bottom" hide-tabs>
<viz-filter field="country" value="USA" />
<viz-filter field="state" value="California,Texas,Washington"></viz-filter>
<viz-parameter name="currency" value="dollars" />
<viz-range-filter field="profit" min="0" max="10000"></viz-range-filter>
<viz-relative-date-filter field="Date" anchor-date="March 17, 2001"
period-type = "Year" range-type = "LastN" range-n = "2"></viz-relative-date-filter>
</tableau-viz>
For more information, see Filter the View and Use Parameters in Embedding Views.
One important difference is that in the JavaScript v2 the filters that were loaded on initialization were added to the URL of the viz. This limited the amount of filters that could be added, because the URLs have a maximum length of 2048 characters. In the Embedding API v3, the filtering occurs separately from the viz URL, but still occurs on initial load.
With the Embedding API v3, you can also add event listeners to the <tableau-viz> web component, using attributes of the web component.
<tableau-viz id="tableauViz"
src="http://my-server/views/my-workbook/my-view"
onMarksSelected="handleMarksSelection">
</tableau-viz>
In this example, handleMarksSelection() is a function that is specified in the JavaScript somewhere to handle an event triggered when someone selects marks in a viz. For more information about events and event listeners in the Embedding API v3, see Add Event Listeners.
All of the above discusses how to initialize the Viz and to configure it during initial load. You will likely want to interact with the Viz — filter, add/remove event listeners, change parameters, query data, etc. — after the Viz loads. The experience for accomplishing those things is very similar to the JavaScript API v2, except where noted below.
See JavaScript code for embedding a TableauViz object.
The relationship between objects/namespaces in the Embedding API v3 remains the same as in the JavaScript API v2. However, the syntax follows modern JavaScript practices and treats related objects as properties instead of returning them in getter methods. For example, if the embedded viz is a dashboard, to access the activeSheet’s worksheets in the JavaScript API v2, you would previously use some code that looks like the following:
// get the currently active sheet (dashboard in this case)
// and get the worksheets in the dashboard.
const sheets = viz.getActiveSheet().getWorksheets();
In the Embedding API v3, you use something like the following to access the active worksheets:
// get the currently active sheet (dashboard in this case)
const activeSheet = viz.workbook.activeSheet;
const worksheets = activeSheet.worksheets;
In v2, many methods returned a collection of objects instead of a native array, allowing you to call .get to find the individual object that you wanted to act upon. For example:
let sameSheet = workbook.getPublishedSheetsInfo().get("Sheet 1");
In v3, these properties return native JavaScript arrays and you can use the JavaScript find() method to access the individual object:
let sameSheet = workbook.publishedSheetsInfo()
.find(sheet => sheet.name == "Sheet 1");
Like the JavaScript API v2, the Embedding API v3 provides a number of asynchronous methods that return promises, such as getFiltersAsync, or activateSheetAsync. Instead of promise chaining, you can use async/await operators to improve the readability of your code. For more information, see Use Async/Await for methods that return promises.
The Embedding API v3 provides new methods for querying data in a workbook and support for existing v2 methods. In the JavaScript API v2 and the Embedding API v3, the data is returned from an embedded view in a DataTable object. The Embedding API v3 provides new methods that employ a DataTableReader to make it easier to parse through large amounts of data. For information about the methods you use to get data with the Embedding API v3, see Get Data From Embedded Views.
The getSummaryDataAsync() remains in v3 with the same syntax. However, getSummaryDataAsync() is deprecated as it might fail when a worksheet has many rows of data. There is a newer method you can use, getSummaryDataReaderAsync(), which is better at handling large amounts of data. In v3, following options have been added to getSummaryDataOptions.
| getSummaryDataOptions | Accepts | Description |
|---|---|---|
columnsToIncludeById |
int[] (columnID) |
Allows you to specify the list of columnIDs to return |
maxRows |
int |
Returns the first set of rows up to the number specified |
includeDataValuesOption |
see includeDataValuesOption |
Serves as a filter on the data values returned |
| includeDataValuesOption | Description |
AllValues |
All values returned. |
OnlyFormattedValues |
Only return the formatted values (as specified by the viz author) and not the native values. |
OnlyNativeValues |
Only return the native values and not the formatted values. |
There are also two new supporting additions:
getSummaryColumnsInfoAsync(): returns only the Column info for when you just need to retrieve metadata about the columns.fieldID property of Column object: for use in columnsToInclude.Much of the what you could do with the JavaScript API v2 you can still do with the Embedding API v3. The following section describes some areas where the features and syntax are similar.
Filtering, selecting marks, and changing parameters after initialization remain the same:
worksheet.applyFilterAsync("Product Type", "Coffee",
FilterUpdateType.Replace);
worksheet.selectMarksByValueAsync("Product", ["Caffe Latte"],
SelectionUpdateType.Replace);
The changeParameterValueAsync method is available in Tableau Server 2022.3 and later (requires the 3.3.0 library or later for this functionality).
workbook.changeParameterValueAsync("Product Type", "Coffee");
Adding and removing event listeners after initialization remains the same:
viz.addEventListener("marksSelection", function (marks) {
changeMySelectionUI(marks);
});
viz.removeEventListener("marksSelection", changeMySelectionUI);