Getting Started - Tableau Embedding API v3

Developer Preview - August 10, 2021
This documentation is preliminary and is subject to change

Use the Tableau Embedding API v3 to integrate Tableau visualizations into your own web applications.

In this section:

Introducing the Embedding API v3

The Embedding API v3 provides you an easy way to embed and integrate Tableau views in your web apps and web pages. The Tableau Embedding API v3 is a replacement for the Tableau JavaScript API v2. The Tableau’s Embedding API v3 features a redesigned process for embedding to make your life easier, to modernize the experience, and to enable new functionality.

Some parts of using the Embedding API v3 are the same as the JavaScript API v2, and others have just slightly different syntax. But the biggest difference is the initialization of the API, which uses web components.

Web components are a standard available in all modern browsers, that 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 a tableau-viz component that you can use to add visualizations to your web pages.
For more information about the differences between the Embedding API v3 and the JavaScript API v2, see the Migrating from Embedding JSAPI v1 or v2 to Embedding API v3

About the Developer Preview

The goal of this Developer Preview of the Embedding API v3 is to let you become familiar with features before the API is released. We encourage you to try the API for your new embedding projects, or for porting existing applications or Embed Code use cases to the Embedding API v3.  Review the API documentation, use the Embedding API v3 and send us your feedback. Throughout the preview, the library will be updated. 

Important! For this preview, the Tableau view you embed must be hosted on the Tableau Online Developer site. To have access to the site, you need to be a member of the Tableau Developer Program. For information, see Get a Tableau Online Developer Site.

Access the Embedding API v3

Like the Tableau JavaScript API, the Embedding API v3 library will be available at release on Tableau Server, Tableau Online, and Tableau Public. For the Developer Preview, it is available from this site: https://embedding.tableauusercontent.com/dist-embedding/tableau.embedding.3.0.latest.beta.js.

To add the Embedding API, you simply link to it from your HTML pages.
For example, to use the library hosted on this site for the preview, you would include this line in your HTML page.

<script type="text/javascript" 
  src="https://embedding.tableauusercontent.com/dist-embedding/tableau.embedding.3.0.latest.beta.js">
</script>
To view the Embedding API reference documentation, that describes the available interfaces, properties, and methods, see https://embedding.tableauusercontent.com/docs-embedding/index.html

Initialize the API

For the Embedding API v3, the initialization step is simplified and can happen all inside of your HTML code, thanks to the new <tableau-viz> web component. For example, the following code is all you need to embed a Tableau view into your HTML pages.
Initializing the API using HTML:
<tableau-viz id="tableauViz"       
  src='http://my-server/views/my-workbook/my-view'>
</tableau-viz>
Note: When the Embedding API v3 is released, Tableau Server, Tableau Online, and Tableau Public, will use the Embedding API v3 web component for the Embed Code option (available from Share button on the toolbar).  The <tableau-viz> component will replace the JavaScript API v1 code currently used. If you have web pages that use Embed Code, you could update them to use the new initialization method. Be sure to include a link to the Embedding API v3 library.
Example of Embed Code, using Embedding API v3:

<script type="text/javascript" 
  src="https://embedding.tableauusercontent.com/dist-embedding/tableau.embedding.3.0.latest.beta.js">
</script>

<tableau-viz id="tableauViz"       
  src='http://my-server/views/my-workbook/my-view'      
  device="phone" toolbar="bottom" hide-tabs>
</tableau-viz>

Tableau viz component configuration

To specify options on how to initialize the viz, you can add those as attributes of the <tableau-viz> element:

<tableau-viz id="tableauViz"     
  src="http://my-server/views/my-workbook/my-view"     
  device="phone" toolbar="bottom" hide-tabs>
</tableau-viz>
Note: for attributes that accept a variety of values, such as src, device, and toolbar the syntax is <property>="<value>". For properties which are Boolean, you either include the flag or omit to use the default value as shown with hide-tabs.
Here is the list of properties you can add to your viz object:
HTML Property
JS Property
Accepted Values
Description
1hide-tabs
Viz.hideTabs
boolean
Indicates whether tabs are hidden or shown.
2toolbar
Viz.toolbar
“top”, “bottom”, “hidden”
Indicates the position of the toolbar or if it should be hidden
3height
Viz.height
(e.g. “800px”)
Can be any valid CSS size specifier. If not specified, defaults to the published height of the view.
4width
Viz.width
(e.g. “800px”)
Can be any valid CSS size specifier. If not specified, defaults to the published height of the view.
5device
Viz.device

Specifies a device layout for a dashboard, if it exists. Values can be default, desktop, tablet, or phone. If not specified, defaults to loading a layout based on the smallest dimension of the hosting iframe element.
6instance-id-to-clone
Viz.instanceIdToClone

Specifies the ID of an existing instance to make a copy (clone) of. This is useful if the user wants to continue analysis of an existing visualization without losing the state of the original. If the ID does not refer to an existing visualization, the cloned version is derived from the original visualization.
7disable-url-actions
Viz.disableUrlActions
boolean
Indicates whether to suppress the execution of URL actions. This option does not prevent the URL action event from being raised.
When adding properties to the <tableau-viz> component, use the HTML Property name.

Filtering during initialization

You can apply filters on the viz by adding elements as children to your objects.

<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>    
  <viz-filter field="state" value="California,Texas,Washington"> </viz-filter>
</tableau-viz>
 

Note that when a filter contains multiple values, the values should be comma-delimited (,) without spaces. 

Interacting with the viz

After you initialize the viz and configure it during initial load, you will likely want to be able to interact with the viz, to apply and change filters, add or remove event listeners, change parameters, or query data. You can do this with the Embedding API v3.

Accessing the viz object

After you create an object in your HTML page, you need to use document.getElementById() method if you want to access the viz object for further customization using JavaScript. You can use the API to apply filters, add event listeners, etc. 
For example, to change the filters applied to a viz, you might use the following code snippet.

let viz = document.getElementById('tableauViz');

// Later 

let sheet = viz.workbook.activeSheet;
sheet.applyFilterAsync("Container", ["Boxes"], tableau.FilterUpdateType.REPLACE);
Note: In the example, the viz will not be ‘interactive’ immediately after you initialize the viz object. If you plan on filtering or doing some interaction immediately after initialization, you should use the firstinteractive event listener to wait for the viz object to be ready.

What’s next


Release Notes

The following lists some of the defects and issues with the specific Developer Preview release of the Embedding API v3.

Release 3.0.0-alpha.38
August 10, 2021