element exists with id="tableauViz" import { TableauViz, } from 'https://public.tableau.com/javascripts/api/tableau.embedding.3.latest.min.js'; const viz = new TableauViz(); viz.src = 'https://my-server/views/my-workbook/my-view'; viz.toolbar = 'hidden'; // add the viz object to the DOM document.getElementById('tableauViz').appendChild(viz); let sheet = viz.workbook.activeSheet; sheet.applyFilterAsync("Container", ["Boxes"], FilterUpdateType.Replace); ``` For more information about the Embedding API v3 interfaces, see the [Embedding API Reference](/current/api/embedding_api/en-us/reference/index.html). * * * ## Importing the Embedding API v3 library The Embedding API v3 library is available as a JavaScript ES6 module and requires some special considerations. To include the library in the HTML code for your web application, you need to set the `type` attribute to `module` in the ` ``` If you’re creating a JavaScript file(s) as part of your embedded web application, to improve load times, import just the features you need from the Embedding API v3 library. For example, you might import `TableauViz` to create the JavaScript object and `TableauEventType` to set an event listener. If you include your JavaScript file in your web application, be sure to set the `type` to `module` in the ` ``` Replace `my-server` with the name of your Tableau Server. For example, if your server is `www.example.com`, to use the Embedding API v3 library you would include this line in your HTML page: ``` ``` For Tableau Cloud, use the following: ``` ``` Replace `Tableau-Pod` with the name of your pod. For example, if your Tableau Pod is `10ax`, the URL would look like this: ``` ``` For Tableau Public, use the following: ``` ``` * * * ## Installing the npm package Starting with Tableau Cloud (December 2023), the [Embedding API v3 library](https://www.npmjs.com/package/@tableau/embedding-api) is available from Node Package Manager (npm). Always use a version of the library that is compatible with the version of Tableau that hosts the view or metric. See [Versions of the Tableau Embedding API](#versions-of-the-tableau-embedding-api). The following command installs the Embedding API v3 library in the `node_modules` folder of the current directory. ```dotnetcli npm i @tableau/embedding-api ``` To install a specific version of the library, append `@` to the command. For example, to install the 3.12.1 library, use the command. ```dotnetcli npm i @tableau/embedding-api@3.12.1 ``` You can verify the installation by checking files in the `node_modules` folder (there should be a `@tableau` folder). If a `package.json` file exists in the directory where you ran the npm command to install the package, and specifies the version of the library to use, the latest version of the library that satisfies the semantic versioning is installed. If no `package.json` exists, or no dependency for the library is specified, the latest version of the library is installed. The following entry in the `package.json` file specifies the `3.12.1` library. The tilde (`~`) in front of the version number indicates that updates to the latest patched minor versions of that library can be used (that is, `3.12.*`). Be sure the version you use matches the version of the library used by the Tableau instance hosting the viz or metric. If you must lock it to a specific version or minor version, omit the tilde (`~`) or wildcard (`*`). ``` "dependencies": { "@tableau/embedding-api": "~3.12.1" } ``` ### Import the npm package In your JavaScript or TypeScript code, import the `TableauViz` object and any other classes and objects you need from the Embedding API v3 library. To simplify your code and improve load times, import just the classes you need, for example `TableauViz` to create the JavaScript object and `TableauEventType` to set an event listener. To import `TableauViz` and `TableauEventType`, use the following statement. Note that you import the library using the scoped package. ``` import { TableauViz, TableauEventType } from '@tableau/embedding-api'; ``` If you import the library, which is an ES module, be sure to specify `"type": "module"` in your `package.json` file. ``` { "name": "tableau-viz-demo", "version": "0.1.0", "private": true, "type": "module", "dependencies": { "@tableau/embedding-api": "~3.12.1", "etc. ....": "this example is not complete", } } ``` * * * ## Installing the React npm package A [React version of the Embedding API v3 library](https://www.npmjs.com/package/@tableau/embedding-api-react) is available from Node Package Manager (npm). For information about installing and using the Tableau Embedding React package, see [Using the Tableau Embedding API React Components](/current/api/embedding_api/en-us/docs/embedding_api_react.html). #### On This Page # Add Custom Context Menus You can create the custom menu items to enable users to run external actions, based upon the marks they’ve selected in a view. The context menu is added to the Uber tooltip that appears when users select marks, as shown in the following example. ![Example of a custom context menu](/current/api/embedding_api/en-us/assets/context_menu_example2.png "Example of a custom context menu on Uber tooltip") The context menu is integrated into the view, and lets you provide users with seamless access to external actions that you choose. * * * ## Context menu methods Starting with version 3.2 of the Embedding API 3.2 library, you can use the following methods to add or remove custom context menu items. For information about each method, click on the links.

Method	Description
`appendContextMenuAsync`	Adds a new menu item.
`renameContextMenuAsync`	Renames the menu header. The default name is Embedded.
`removeContextMenuAsync`	Removes the context menu and menu item.

The following section shows the steps you go through to add a menu item to the Uber tooltip and then tie that menu item to drive an external action. ## Add a custom context menu item To add a custom context menu item, use the `Worksheet.appendContextMenuAsync()` method. The method takes two parameters. The first specifies the location of the context menu. In this case, it is `ApiMenuType.Ubertip`, the only location currently supported. The second parameter specifies the context menu options and specifies the text that appears for the menu item. If the method succeeds, it returns the identifier for the menu item that was added. You use this identifier to remove the menu item or to know which menu item was clicked. For example, the following code snippet adds a menu item called “Run my app.” The ID returned by the `appendContextMenuAsync` method and the name of the menu item are mapped and stored in an array. ``` // The following assumes that you are calling this code from an `async` // function. ... const menuItemName = "Run my app"; const config = { displayName: menuItemName }; const menuItemMap = {}; // Stores identifiers of newly inserted context menu items try { const menuItemId = await worksheet.appendContextMenuAsync(ApiMenuType.Ubertip, config); menuItemMap[menuItemName] = menuItemId; } catch (e) { alert("An exception was thrown: " + e); } finally { return; } ... ``` ## Rename the default menu header By default, the menu heading in the Uber tip says “Embedded.” To change this to something that is more descriptive of the menu item(s) that you are adding, use the `Worksheet.renameContextMenuAsync()` method. In this case, the code snippet shows how you change the name of the menu header to “Actions” from “Embedding” (the default heading). You can use the `menuDescription` to provide a tooltip for the menu. ``` // The following assumes that you are calling this code from an `async` // function. ... const menuName = "Actions"; const menuDescription = "Run custom actions"; try { await worksheet.renameContextMenuAsync(ApiMenuType.Ubertip, menuName, menuDescription); } catch (e) { alert("An exception was thrown: " + e); } finally { return; } ... ``` ## Add an event listener for the custom context menu item Add an event listener and create an event handler for your custom menu item. You need to specify the event type as a `TableauEventType.CustomMarkContextMenuEvent`. The following code snippet specifies an event handler, called _customMarkEventHandler_, to take action when someone clicks the context menu item. ``` ... // Add the event listener viz.addEventListener(TableauEventType.CustomMarkContextMenuEvent, customMarkEventHandler); ... ``` ## Create the event handler for the menu item When the event occurs, the event handler is called and it takes the `CustomMarkContextMenuEvent` as a parameter. From the details of `CustomMarkContextMenuEvent`, you can get the identifier for the menu item that was clicked and the marks that were selected. You can use this information to take further action. In this example, the action is to call another method (`displaySelectedMarks`) that displays information about the selected marks. In your own code, you could use the selected data to call into another application or to drive actions within your web application. ``` // Get the context menu id function setMenuItemId(customMarkContextMenuEvent) { contextMenuId = customMarkContextMenuEvent.detail.getContextMenuId(); } function getMenuItemId() { return contextMenuId; } // define the event handler for the context menu item function customMarkEventHandler(customMarkContextMenuEvent) { console.log("Reached the customMarkContextMenuEvent"); // check the context menu id and run custom actions with the marks selected setMenuItemId(customMarkContextMenuEvent); return customMarkContextMenuEvent.detail.getSelectedMarksAsync().then(displaySelectedMarks); } // example action that shows how to process display the marks function displaySelectedMarks(marks) { const html = []; for (let markIndex = 0; markIndex < marks.data[0].data.length; markIndex++) { const columns = marks.data[0].columns; html.push(`Mark ${markIndex}, MenuId ${getMenuItemId()}:

Field Name: ${columns[colIndex].fieldName}`); html.push(`
Value: ${marks.data[0].data[markIndex][colIndex].formattedValue}

"); const infoDiv = document.getElementById("markDetails"); infoDiv.innerHTML = html.join(''); } } ``` #### On This Page # Add Event Listeners to Tableau Pulse 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. * * * ## Supported Tableau Pulse events The 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.
`PulseMetricSizeChanged`	`pulsemetricsizechanged`	Raised when the size of the Pulse metric changes.
`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.

* * * ## Add an event listener using the addEventListener() method 1. Get the `TableauPulse` object. 2. Add the event listener by calling the JavaScript `addEventListener()` method on the `TableauPulse` object. 3. Specify the type of event and the event handler. The type of the event must be one of the supported types defined in the `TableauEventType` enumeration (see [Supported Pulse events](#supported-tableau-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. ### Example: Adding an event listener for a `FirstInteractive` event In 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 }; ``` * * * ## Remove an event listener 1. Get the `TableauPulse` object. 2. Remove the event listener by calling the JavaScript `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); ``` * * * ## Examples: Tableau Pulse event listeners The following section shows how you could add event listeners to embedded Pulse metrics to gather information or to take further action. * * * ### Adding an event listener for a `FirstPulseMetricSizeKnown` event You 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`; }); ``` * * * ### Adding an event listener for a `PulseUrlChanged` event When 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) }); ``` * * * ### Adding an event listener for a `PulseTimeDimensionChanged` event You 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); }); ``` * * * ### Adding an event listener for a `PulseFiltersChanged` event You 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); }); ``` * * * ### Adding an event listener for a `PulseInsightDiscovered` event You 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](https://help.tableau.com/current/online/en-us/pulse_insights_platform_insight_types.htm). ``` // 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); }); ``` * * * ### Adding an event listener for a `PulseError` event You 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); }); ``` * * * ### Adding an event listener for a `PulseMetricSizeChanged` event You can add an event listener to capture the details when the size of a Pulse metric changes. 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. ``` tableauPulse.addEventListener(TableauEventType.PulseMetricSizeChanged, (e) => { console.log(TableauEventType.PulseMetricSizeChanged, e.detail); const { width, height } = e.detail; tableauPulse.iframe.style.width = `${width}px`; tableauPulse.iframe.style.height = `${height}px`; }); ``` #### On This Page # Add Event Listeners to the Embedded Tableau View You can use event listeners to create actions based on events that happen with the view. The event listener registers a callback handler, that handler method gets called when an event occurs. The `viz` object acts as the central event hub. This way you only have to go to one place for all events. It also means that events can be raised on an object that might not have been created yet. For example, the `MarkSelectionChanged` event can be raised for a particular sheet even though the `sheet` object hasn’t been created yet. Each event contains an anonymous object with information relating to that event, such as the `sheet` the event occurred on. Listening to an event is done by calling `viz.addEventListener(type, callback)` and passing in a callback function. Here’s an example of listening to an event, where the name of the custom function is `handleFirstInteractive()`. You would define this function in your JavaScript code: ``` const tableauViz = document.getElementById('tableauViz'); tableauViz.addEventListener(TableauEventType.FirstInteractive, handleFirstInteractive); ``` There is an even easier way to add an event listener by adding an attribute to the `` or `` web component. Both of these methods are described in the following section. * * * ## Supported events The Embedding API supports the following event types (`TableauEventType`). The type of event you can listen for depends upon whether you’re embedding a view (using a `` web component or `TableauViz` object, for example) or embedding web authoring (using a`` web component or `TableauAuthoringViz` object). Some events are available when you’re embedding a view in viewing mode. Others apply only for embedded web authoring. And some apply to both viewing and authoring.

`TableauEventType`	String literal	Web Attribute	Description	Component
`CustomMarkContextMenuEvent`	`"custommarkcontextmenu"`	`onCustomMarkContextMenuEvent`	Raised when a custom mark context menu is clicked. See Add a Custom Context Menu	Viewing
`CustomViewLoaded`	`"customviewloaded"`	`onCustomViewLoaded`	Raised when a custom view has finished loading. This event is raised after the callback function for `FirstInteractive` (if any) has been called.	Viewing
`CustomViewRemoved`	`"customviewremoved"`	`onCustomViewRemoved`	Raised when a custom view has been removed.	Viewing
`CustomViewSaved`	`"customviewsaved"`	`onCustomViewSaved`	Raised when a custom view has been saved (newly created or updated).	Viewing
`CustomViewSetDefault`	`"customviewsetdefault"`	`onCustomViewSetDefault`	Raised when a custom view has been set as the default view for a workbook.	Viewing
`EditButtonClicked`	`"editbuttonclicked"`	`onEditButtonClicked`	Raised when the user clicks the Edit button.	Viewing
`EditInDesktopButtonClicked`	`"editindesktopbuttonclicked"`	`onEditInDesktopButtonClicked`	Raised when the user clicks the Edit In Desktop button.	Authoring, Viewing
`FilterChanged`	`"filterchanged"`	`onFilterChanged`	Raised when any filter has a changed state.	Viewing
`FirstInteractive`	`"firstinteractive"`	`onFirstInteractive`	Raised when the `viz` first becomes interactive after loading.	Authoring, Viewing
`FirstVizSizeKnown`	`"firstvizsizeknown"`	`onFirstVizSizeKnown`	Raised when the size of the `viz` object is known. You can use this event to perform tasks such as resizing the elements surrounding the `viz` object after the object’s size has been established.	Authoring, Viewing
`MarkSelectionChanged`	`"markselectionchanged"`	`onMarkSelectionChanged`	Raised when the selected marks in a `viz` have changed.	Viewing
`ToolbarStateChanged`	`"toolbarstatechanged"`	`onToolbarStateChanged`	Raised when a toolbar button or control becomes available or becomes unavailable.	Viewing
`TabSwitched`	`"tabswitched"`	`onTabSwitched`	Raised after a tab switch occurs (the active sheet has changed). Guarantees the viz object will be interactive after this.	Viewing
`ParameterChanged`	`"parameterchanged"`	`onParameterChanged`	A parameter has had its value modified. You can use this event type with Parameter objects.	Viewing
`UrlAction`	`"urlaction"`	`onUrlAction`	Raised when Raised when a URL action occurs. See the `UrlActionEvent` class.	Viewing
`WorkbookPublished`	`"workbookpublished"`	`onWorkbookPublished`	Raised when the workbook has been published.	Authoring
`WorkbookPublishedAs`	`"workbookpublishedas"`	`onWorkbookPublishedAs`	Raised when “publish as” is successful.	Authoring
`WorkbookReadyToClose`	`"workbookreadytoclose"`	`onWorkbookReadyToClose`	Raised when the workbook is ready to close.	Authoring

* * * **Note** Use the `TableauEventType` enum (for example, `TableauEventType.MarkSelectionChanged`) when you add or remove the event listener using the Tableau Embedding API and the `addEventListener` and `removeEventLister` methods. * * * ## Using simplified event handling Starting in Embedding API v3 (version 3.3), you can link your custom event handler to an event declaratively in the `` or `` web component by specifying the event type attribute. The following example calls a JavaScript function to handle the `onMarkSelectionChanged` event. When a `onMarkSelectionChanged` event occurs, the `handleMarksSelection()` event handler is called. You define the event handler in your JavaScript code. ``` ... ... ``` The following example shows a web authoring component that adds an event listener to handle a published event. ``` ... ... ``` Before v3.3, you could only configure an event listener in JavaScript using the `addEventListener` method. The event type attribute makes it easy to add custom event handlers. * * * ## Add an event listener using the addEventListener() method 1. Get the `viz` object. 2. Add the event listener by calling `addEventListener` and specifying the type of event and the callback method to call. The name of the event must be one of the supported types defined in the `TableauEventType` enumeration. The callback method must handle the event object raised. ``` async function getSelectedMarks(event) { const marksSelected = await event.detail.getMarksAsync(); const numMarks = marksSelected.data[0].data.length; console.log(`${numMarks} marks Selected`); } let viz = document.getElementById('tableauViz'); viz.addEventListener(TableauEventType.MarkSelectionChanged, getSelectedMarks); ``` ## Remove an event listener 1. Get the `viz` object. 2. Remove the event listener by using the `removeEventListener` method and specifying the name of your event handler. For example, to remove the event handler for the `TableauEventType.MarkSelectionChanged` event called, `getSelectedMarks` you might use something like the following: ``` let viz = document.getElementById('tableauViz'); viz.removeEventListener(TableauEventType.MarkSelectionChanged, getSelectedMarks); ``` ## Add an event listener after the viz is first loaded In some cases you might want to take actions right after the view is first loaded. For example, you might want to set the filtering or perform some other customization for the person who is viewing the embedded viz. You can do this by adding an event listener on `TableauEventType.FirstInteractive` event type. In addition, you can wrap the call in a `window.onload` event handler, so that your `FirstInteractive` event is called after all the dependent resources have been loaded. ``` window.onload = function () { let viz = document.getElementById('tableauViz'); viz.addEventListener(TableauEventType.FirstInteractive, async (event) => { console.log(`Event type is ${event.type}`); // call methods to run immediately after loading }); } ``` #### On This Page - AnalyticsObjectType # Enumeration AnalyticsObjectType - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:7 ##### Index ### Enumeration Members [Cluster](#cluster) [Forecast](#forecast) [TrendLine](#trendline) ## Enumeration Members ### Cluster[](#cluster) Cluster: "cluster" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:8 ### Forecast[](#forecast) Forecast: "forecast" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:9 ### TrendLine[](#trendline) TrendLine: "trend-line" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:10 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Enumeration Members [Cluster](#cluster)[Forecast](#forecast)[TrendLine](#trendline) - Annotation # Interface Annotation Represents an annotation in a worksheet. interface Annotation { [annotationHTML](#annotationhtml): string; [annotationId](#annotationid): number; [annotationText](#annotationtext): string; [annotationType](#annotationtype): [AnnotationType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/AnnotationType.html); [tupleId](#tupleid): number; } - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/AnnotationInterfaces.ts:6 ##### Index ### Properties [annotationHTML](#annotationhtml) [annotationId](#annotationid) [annotationText](#annotationtext) [annotationType](#annotationtype) [tupleId](#tupleid) ## Properties ### annotationHTML[](#annotationhtml) annotationHTML: string #### Returns[](#returns) The formatted annotation as a HTML string. HTML is currently not accepted when adding an annotation. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/AnnotationInterfaces.ts:10 ### annotationId[](#annotationid) annotationId: number #### Returns[](#returns-1) Unique id representing the annotation. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/AnnotationInterfaces.ts:15 ### annotationText[](#annotationtext) annotationText: string #### Returns[](#returns-2) The plain text of the annotation. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/AnnotationInterfaces.ts:20 ### annotationType[](#annotationtype) annotationType: [AnnotationType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/AnnotationType.html) #### Returns[](#returns-3) The annotation type. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/AnnotationInterfaces.ts:25 ### tupleId[](#tupleid) tupleId: number #### Returns[](#returns-4) Unique tuple representing the mark that is being annotated. The tupleId will be 0 for Area or Point annotations. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/AnnotationInterfaces.ts:30 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Properties [annotationHTML](#annotationhtml)[annotationId](#annotationid)[annotationText](#annotationtext)[annotationType](#annotationtype)[tupleId](#tupleid) - AnnotationType # Enumeration AnnotationType - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:13 ##### Index ### Enumeration Members [Area](#area) [Mark](#mark) [Point](#point) ## Enumeration Members ### Area[](#area) Area: "area" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:16 ### Mark[](#mark) Mark: "mark" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:14 ### Point[](#point) Point: "point" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:15 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Enumeration Members [Area](#area)[Mark](#mark)[Point](#point) - ApiMenuType # Enumeration ApiMenuType Represents the location of a context menu where users can add external menu items. - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/Enums.ts:494 ##### Index ### Enumeration Members [Ubertip](#ubertip) ## Enumeration Members ### Ubertip[](#ubertip) Ubertip: "ubertip" External menu item will be injected in ubertip dialog - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/Enums.ts:496 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Enumeration Members [Ubertip](#ubertip) - AskData # Interface AskData The interface for the top level AskData object. #### Deprecated[](#deprecated) interface AskData { [debug](#debug)?: boolean; [height](#height)?: string | number; [iframeAttributeClass](#iframeattributeclass)?: string; [iframeAttributeLoading](#iframeattributeloading)?: string; [iframeAttributeStyle](#iframeattributestyle)?: string; [iframeAuth](#iframeauth)?: boolean; [origin](#origin)?: string; [showEmbed](#showembed)?: boolean; [showPin](#showpin)?: boolean; [showSave](#showsave)?: boolean; [showShare](#showshare)?: boolean; [src](#src)?: null | string; [token](#token)?: string; [width](#width)?: string | number; } #### Hierarchy ([View Summary](https://help.tableau.com/current/api/embedding_api/en-us/reference/hierarchy.html#AskData)) - [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html) - AskData - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/AskDataInterfaces.ts:65 ##### Index ### Properties [debug?](#debug) [height?](#height) [iframeAttributeClass?](#iframeattributeclass) [iframeAttributeLoading?](#iframeattributeloading) [iframeAttributeStyle?](#iframeattributestyle) [iframeAuth?](#iframeauth) [origin?](#origin) [showEmbed?](#showembed) [showPin?](#showpin) [showSave?](#showsave) [showShare?](#showshare) [src?](#src) [token?](#token) [width?](#width) ## Properties ### `Optional`debug[](#debug) debug?: boolean Indicates whether the non-minified version of JavaScript is loaded. If specified (or set to true), the non-minified version is used for both the local component and the Tableau Server visualization (if enabled). If not specified (or set to false), the minified version of the JavaScript files are loaded. ```

``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[debug](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#debug) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:50 ### `Optional`height[](#height) height?: string | number Represents height in pixels Can be any valid CSS size specifier. If not specified, defaults to the published height of the view. Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[height](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#height) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:20 ### `Optional`iframeAttributeClass[](#iframeattributeclass) iframeAttributeClass?: string The value of the 'class' attribute of the embedded iframe providing access to any custom selectors defined in the `` child tag. ```

.red-border { border: 1px solid red; }

``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[iframeAttributeClass](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#iframeattributeclass) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:101 ### `Optional`iframeAttributeLoading[](#iframeattributeloading) iframeAttributeLoading?: string The value of the 'loading' attribute of the embedded iframe. See: [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#loading](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#loading) ```

``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[iframeAttributeLoading](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#iframeattributeloading) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:74 ### `Optional`iframeAttributeStyle[](#iframeattributestyle) iframeAttributeStyle?: string The value of the 'style' attribute of the embedded iframe. ```

``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[iframeAttributeStyle](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#iframeattributestyle) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:85 ### `Optional`iframeAuth[](#iframeauth) iframeAuth?: boolean Indicates whether to use the old auth mechanism for authentication which happens inside the iframe. If specified, VizLoadErrorEvents triggered due to auth failures will not be thrown. ```

``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[iframeAuth](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#iframeauth) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:62 ### `Optional`origin[](#origin) origin?: string Used for telemetry ``` ``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[origin](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#origin) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/AskDataInterfaces.ts:58 ### `Optional`showEmbed[](#showembed) showEmbed?: boolean Indicates whether the embed button is hidden or visible. ``` ``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[showEmbed](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#showembed) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/AskDataInterfaces.ts:26 ### `Optional`showPin[](#showpin) showPin?: boolean Indicates whether the pin button is hidden or visible. ``` ``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[showPin](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#showpin) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/AskDataInterfaces.ts:34 ### `Optional`showSave[](#showsave) showSave?: boolean Indicates whether the save button is hidden or visible. ``` ``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[showSave](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#showsave) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/AskDataInterfaces.ts:42 ### `Optional`showShare[](#showshare) showShare?: boolean Indicates whether the share button is hidden or visible. ``` ``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[showShare](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#showshare) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/AskDataInterfaces.ts:50 ### `Optional`src[](#src) src?: null | string The viz src Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[src](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#src) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:8 ### `Optional`token[](#token) token?: string The token used for authorization ```

``` Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[token](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#token) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:37 ### `Optional`width[](#width) width?: string | number Represents width in pixels Can be any valid CSS size specifier. If not specified, defaults to the published width of the view. Inherited from [AskDataSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html).[width](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskDataSettings.html#width) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:14 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Properties [debug](#debug)[height](#height)[iframeAttributeClass](#iframeattributeclass)[iframeAttributeLoading](#iframeattributeloading)[iframeAttributeStyle](#iframeattributestyle)[iframeAuth](#iframeauth)[origin](#origin)[showEmbed](#showembed)[showPin](#showpin)[showSave](#showsave)[showShare](#showshare)[src](#src)[token](#token)[width](#width) - AskDataSettings # Interface AskDataSettings #### Deprecated[](#deprecated) interface AskDataSettings { [debug](#debug)?: boolean; [height](#height)?: string | number; [iframeAttributeClass](#iframeattributeclass)?: string; [iframeAttributeLoading](#iframeattributeloading)?: string; [iframeAttributeStyle](#iframeattributestyle)?: string; [iframeAuth](#iframeauth)?: boolean; [origin](#origin)?: string; [showEmbed](#showembed)?: boolean; [showPin](#showpin)?: boolean; [showSave](#showsave)?: boolean; [showShare](#showshare)?: boolean; [src](#src)?: null | string; [token](#token)?: string; [width](#width)?: string | number; } #### Hierarchy ([View Summary](https://help.tableau.com/current/api/embedding_api/en-us/reference/hierarchy.html#AskDataSettings)) - [WebComponentSettingsShared](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentSettingsShared.html) - [WebComponentLocalSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html) - AskDataSettings - [AskData](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/AskData.html) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/AskDataInterfaces.ts:19 ##### Index ### Properties [debug?](#debug) [height?](#height) [iframeAttributeClass?](#iframeattributeclass) [iframeAttributeLoading?](#iframeattributeloading) [iframeAttributeStyle?](#iframeattributestyle) [iframeAuth?](#iframeauth) [origin?](#origin) [showEmbed?](#showembed) [showPin?](#showpin) [showSave?](#showsave) [showShare?](#showshare) [src?](#src) [token?](#token) [width?](#width) ## Properties ### `Optional`debug[](#debug) debug?: boolean Indicates whether the non-minified version of JavaScript is loaded. If specified (or set to true), the non-minified version is used for both the local component and the Tableau Server visualization (if enabled). If not specified (or set to false), the minified version of the JavaScript files are loaded. ```

.red-border { border: 1px solid red; }

``` Inherited from [WebComponentSettingsShared](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentSettingsShared.html).[token](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentSettingsShared.html#token) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:37 ### `Optional`width[](#width) width?: string | number Represents width in pixels Can be any valid CSS size specifier. If not specified, defaults to the published width of the view. Inherited from [WebComponentLocalSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html).[width](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html#width) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:14 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Properties [debug](#debug)[height](#height)[iframeAttributeClass](#iframeattributeclass)[iframeAttributeLoading](#iframeattributeloading)[iframeAttributeStyle](#iframeattributestyle)[iframeAuth](#iframeauth)[origin](#origin)[showEmbed](#showembed)[showPin](#showpin)[showSave](#showsave)[showShare](#showshare)[src](#src)[token](#token)[width](#width) # Authentication and Embedding When you embed Tableau content into your web application, you must consider whether users have permission to see that content. This is because when someone accesses the Tableau content in your web application, the same authentication protocols apply as if they were accessing the view on Tableau directly. For example, if you’re writing code to embed a view from Tableau Public, no authentication is required. However, if your code is getting a view from Tableau Cloud or a hosted instance of Tableau Server, authentication is typically required. If the user isn’t already signed in to the server, Tableau redirects the request for a view to the Tableau sign in page, and the user must provide a username and password. After the user has signed in, the browser caches session information, and the user doesn’t have to sign in again unless they have explicitly signed out of Tableau, or until the session token expires. Tableau 2021.4 introduced connected apps for authenticating and authorizing users of embedded content: direct trust and OAuth 2.0 trust. These options use JSON Web Tokens (JWTs) and control permissions and access to projects and control where content can be embedded. Tableau 2025.3 introduced an additional option for authenticating users of embedded content: unified access tokens (UATs). UATs facilitate authentication to embedded content and control access to content by using JSON Web Tokens (JWTs). This topic discusses connected apps and UATs and how you can use them for authentication. For information about the other ways of authentication, see the Tableau Cloud and Tableau Server documentation. For information about the authentication options, see the following: - For Tableau Cloud - [Site Authentication](https://help.tableau.com/current/online/en-us/security_auth.htm) in the Tableau Cloud Help. - For Tableau Server - [Authentication (Windows)](https://help.tableau.com/current/server/en-us/security_auth.htm) or [Authentication (Linux)](https://help.tableau.com/current/server-linux/en-us/security_auth.htm) in the Tableau Server Help. * * * ## Unified access tokens (Tableau Cloud only) Starting in Tableau 2025.3, you can use unified access tokens (UATs), configured through Tableau Cloud Manager (TCM), to enable and authorize access to embedded views using JSON Web Token (JWT). When users visit the embedded content in your web application, the embedded content is scoped to the privileges defined in the JWT. UATs, like connected apps, enable you to control the views and projects that users of your embedded application have access to. For more information about UATs, see [Unified Access Tokens](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html) in the Tableau Cloud Manager REST API Help. ## Tableau connected apps While having users sign in to Tableau generally works, assuming your browser allows 3rd-party cookies, it’s not necessarily the best experience for users of your embedded application. Starting in Tableau 2021.4, when you embed views using the Embedding API v3, you have two options: - Using direct trust, you can configure Tableau to use a connected app for authentication. - Using OAuth 2.0 trust, you can use an external authorization server (EAS) if you’re using an identity provider (IdP) with Tableau Cloud or Tableau Server to authenticate users. Connected apps provide a way to create and manage explicit trust relationships between your Tableau Cloud site or Tableau Server, and custom applications where Tableau content is embedded. You can control the views and projects that users of your embedded application have access to. **Note:** For users to successfully authenticate when they access embedded content, browsers must be configured to allow third-party cookies. ### Configure a connected app Connected apps have a trust relationship with Tableau. You can use Tableau Cloud, Tableau Server, or the Tableau REST API to configure a connected app for your embedded web application. After you set up the connected app, your users are able to authenticate through a JSON Web Token (JWT) generated by your web server by using a shared secret signed by Tableau. When a user visits the embedded content in your web application, the embedded content is scoped to the privileges defined in the JWT. #### Overview for enabling a connected app **Important:** When you embed a Tableau view in your application, your application must conform with your Tableau licensing, which means you must generate a JWT dynamically for each enabled user. Never embed the credentials for one user in your connected app and then use that as authorization for others. For information about usage-based licensing and special licensing for embedded analytics, see [Understanding License Models](https://help.tableau.com/current/online/en-us/license_product_keys.htm). ##### Direct trust There are five parts to enabling a connected app. 1. As a Tableau Cloud site administrator or Tableau Server administrator, sign in to Tableau and create a new connected app. Alternatively, you can use the Tableau REST API’s connected apps methods to create a new connected app. Make note of the client ID, as you’ll need this ID to create the JWT. 2. For security, use the domain allowlist to make sure that Tableau content is only embedded in locations that you allow. See one of the following: - For Tableau Cloud - [Domain allowlist rules (embedding workflows only)](https://help.tableau.com/current/online/en-us/connected_apps_direct.htm#domain-allowlist-rules-embedding-workflows-only) - For Tableau Server - [Domain allowlist rules (embedding workflows only)](https://help.tableau.com/current/server/en-us/connected_apps_direct.htm#domain-allowlist-rules-embedding-workflows-only) 3. Generate the secret for the connected app. Make note of this secret ID and secret value as you’ll need these values when you generate the JWT. 4. Configure the web server that hosts your embedded application to generate the JWT. The JWT is generated dynamically for each user. If you’re not using usage-based licensing, you must provide an appropriate user name in the JWT. For embedding, the JWT must include a registered claim for the scope (`"scp"`). See [Pass the JWT to the Tableau web component](#pass-the-jwt-to-the-tableau-web-component) for more information. There are JWT libraries and packages in various languages that you can use to build the JWT. 5. After you have the JWT, you must pass the JWT to the ``, ``, or `` web component. For more information about configuring a connected app using direct trust, see the following: - For Tableau Cloud - [Configure Connected Apps with Direct Trust](https://help.tableau.com/current/online/en-us/connected_apps_direct.htm) in the Tableau Cloud Help - For Tableau Server - [Configure Connected Apps with Direct Trust](https://help.tableau.com/current/server-linux/en-us/connected_apps_direct.htm) in the Tableau Server Help **Note:** You can use group names in the JWT, but [group sets](https://help.tableau.com/current/online/en-us/group_sets.htm) aren't supported. For information about using dynamic group memberships in the embedding workflow, see [Dynamic group membership using assertions](https://help.tableau.com/current/online/en-us/to_add_users_groups.htm#dynamic-group-membership-using-assertions). ##### OAuth 2.0 trust As a Tableau Cloud site administrator or Tableau Server administrator, you can register an external authorization server (EAS) to establish a trust relationship between Tableau and the EAS. By establishing a trust relationship, you’re able to provide your users a single sign-on (SSO) experience to Tableau content embedded in your custom applications through the identity provider (IdP) you’ve already configured for Tableau. When embedded Tableau content is loaded in your custom application, a standard OAuth flow is used. After users successfully sign in to the IdP, they’re then automatically signed in to Tableau. To use a connected app with OAuth 2.0 trust, your Tableau Cloud site or Tableau Server instance must be using an identity provider (IdP) for authentication. The EAS must be set up to provide a JSON Web Token (JWT). You use the JWT when you embed the Tableau view as a web component in your application. You must configure the JWT so that it includes a registered claim for the scope (`"scp"`). See [Pass the JWT to the Tableau web component](#pass-the-jwt-to-the-tableau-web-component) for more information. There are JWT libraries and packages in various languages that you can use to build the JWT. For more information about configuring a connected app using OAuth 2.0 trust, see the following: - For Tableau Cloud - [Configure Connected Apps with OAuth 2.0 Trust](https://help.tableau.com/current/online/en-us/connected_apps_eas.htm) in the Tableau Cloud Help - For Tableau Server - [Configure Connected Apps with OAuth 2.0 Trust](https://help.tableau.com/current/server-linux/en-us/connected_apps_eas.htm) in the Tableau Server Help * * * ## Pass the JWT to the Tableau web component Whether you’re configuring your embedded web application to use a unified access token (UAT) or connected app, you must configure the JWT so that it includes a registered claim for the scope (`"scp"`). For example, for embedded views, you set the value as `tableau:views:embed`. | Embedding Element | Scope (`scp`) | | --- | --- | | TableauViz | `tableau:views:embed` | | TableauAuthoringViz | `tableau:views:embed_authoring`, `tableau:views:embed` | | TableauPulse | `tableau:insights:embed` | | AskData | `tableau:ask_data:embed` \* | | Metrics | `tableau:metrics:embed` \* | \* Note: In October 2023, Tableau retired the ability to embed metrics in Tableau Cloud and Tableau Server version 2023.3. Ask Data will be retired in Tableau Cloud in February 2024 and in Tableau Server version 2024.2. You can specify more than one value for the scope. For example, for embedded web authoring you also need to include the scope for viewing (`tableau:views:embed_authoring` and `tableau:views:embed`). The scope respects the permissions a user already has configured in Tableau, which allows the user to interact with the view the way they can on Tableau directly. You then explicitly pass the JWT that is generated by the EAS or by your web server to the ``, ``, or `` web component. You include the JWT by using the `token` attribute. For example, you could programmatically build the JWT based on the connected app secrets and then add it to the `` web component as the `token` attribute, or if you’re using JavaScript assign the JWT to the `TableauViz.token` property. ``` ``` For sample code showing how you can construct the JWT, see the [connected-apps-jwt-samples](https://github.com/tableau/connected-apps-jwt-samples) repository on GitHub. This repository contains samples in popular programming languages for generating a JWT. * * * ## About Tableau site settings for authentication Several Tableau site settings interact with or affect authentication for embedded content. This section describes key settings related to connected apps, user attributes, on-demand access, and dynamic group membership through assertions. ### General embedding When you embed a view that has been configured to use a Tableau connected app for authentication, the domain allowlist of the connected app isn’t affected by the [Tableau Site settings for embedding](/current/api/embedding_api/en-us/docs/embedding_api_site.html). For more information about how the site settings relate to connected apps, see the [Tableau site settings for embedding and connected apps](/current/api/embedding_api/en-us/docs/embedding_api_site.html#the-tableau-site-settings-for-embedding-and-connected-apps). ### User attributes The Tableau Cloud or Tableau Server site setting, **Control User Access in Authentication Workflows** enables user attribute functions used in embedded content to accept the passing of user attributes from a JSON Web Token (JWT). To enable this setting, do the following: Sign in to Tableau Cloud as a site administrator or Tableau Server as an administrator, select **Settings** > **Authentication**, and then select the **Enable capture of user attributes in authentication workflows** checkbox. Alternatively, you can use the [Update Site](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_site.htm#update_site) endpoint using the Tableau REST API to programmatically enable the _attribute-capture-enabled_ setting. ### On-demand access (Tableau Cloud only) On-demand access isn’t enabled through a Tableau Cloud site setting. Instead, to enable the on-demand access capability for a group, when creating or editing a group, you must select the **Allow on-demand access** checkbox. For more information about creating groups, see [Create a Group and Add Users to It](https://help.tableau.com/current/online/en-us/to_add_users_groups.htm). You can also enable this capability using the Tableau REST API. For more information, see the [Create Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#create_group) and [Update Group](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_users_and_groups.htm#update_group) methods in the Tableau REST API Help. ### Dynamic group membership through assertions The Tableau Cloud site or Tableau Server setting, **Assertions for Group Membership**, enables you to dynamically control group members through assertions. Two custom group membership claims must be included in the JWT assertion to specify group membership. To enable this setting, do the following: Sign in to Tableau Cloud as a site administrator or Tableau Server as an administrator, go to the **Settings** page (for a multi-site Tableau Server, go to the Settings page for all sites). Under the **Assertions for Group Membership** heading, select the **Allow group assertions to enable group membership through SAML or JWT assertions** checkbox. * * * ## Error handling for connected apps Starting with Tableau 2023.2 and the Embedding API v3 library version 3.6, there’s a new authentication flow and an event type you can use to help catch and identify errors that occur when you’re using a connected app or an external authorization server (EAS) for authentication. This event is triggered when an error happens during the initialization of the web component, which includes views (authoring and viewing) and Ask Data web components. The errors include authentication errors, connectivity errors, etc. ### Embedding multiple view or Ask Data lenses If you’re embedding multiple views or Ask Data lenses in a web application using connected apps for authentication, be sure to use the same JWT for all embedded components. Using different tokens for each embedded component could lead to unexpected behavior, sometimes loading correctly and sometimes prompting users to sign in. Note: Ask Data will be retired in Tableau Cloud in February 2024 and in Tableau Server version 2024.2. ### Compatibility This authentication flow for connected apps, including the new error handling capability and related bug fixes, is only available if you’re using version 3.6 (or later) of the Embedding API library and Tableau 2023.2 (or later). Generally, you should always use the latest version of the library from the Tableau instance that hosts the view you’re embedding. If for some reason you need to use the authentication flow for connected apps that was available in previous versions of Tableau and the Embedding API, the 3.6 version of the library provides an attribute that enables that behavior. **Note:** Using the older flow doesn’t provide the error handling capability available with the 3.6 library and Tableau 2023.2. For more information, see [Use the iframe-auth attribute to enable previous authorization flow](#use-the-iframe-auth-attribute-to-enable-previous-authorization-flow). ### Add an event listener for load and initialization errors You can set up an event listener for a view loading error using this new event type, `TableauEventType.VizLoadError`, or the web component attribute, `onVizLoadError`. In your callback function for the event handler, you can now take action depending upon the connected app error codes. For the list of error codes, see [Troubleshoot Connected Apps](https://help.tableau.com/current/online/en-us/connected_apps_troubleshoot.htm). For example, in a `` web component, you could add the event listener for the `onVizLoadError` and specify the callback function to handle the event (in this case, `handleLoadError`). You define your `handleLoadError()` function in your JavaScript code. ``` ``` To add the same event listener in JavaScript, you first access the `TableauViz` object from the DOM, and then call `addEventListener` with the event type (`TableauEventType.VizLoadError`). ``` const tableauViz = document.getElementById('tableauViz'); tableauViz.addEventListener(TableauEventType.VizLoadError, handleLoadError); ``` In your event handler, you can capture the error code from the event payload and then use the status and error codes for debugging, or take action based on the error code returned. ``` function handleLoadError (e) { const message = JSON.parse(e.detail.message); console.log(message); // do something based on the error code in e.detail } ``` Another option is to use information about the error to determine whether to use the previous authentication flow, or whether to bypass the connected app authentication path completely and revert to the Tableau login prompt. The following example shows how you could create an event handler that switches to the previous flow when an `unknown-auth-error` occurs by setting the `iframeAuth` property. If a different load error occurs, the event handler removes the `token` attribute, so that the user sees the Tableau login prompt. ``` // Error handling logic tableauViz.addEventListener(TableauEventType.VizLoadError, (e) => { if (e.detail.errorCode == "unknown-auth-error") { e.target.iframeAuth = true; } else { e.target.removeAttribute("token"); // prompt user to login } }); ``` ### Use the iframe-auth attribute to enable previous authorization flow Starting with the 3.6 library and Tableau 2023.2, the authentication flow for connected apps is handled through the Embedding API. With previous versions of the library and with prior versions of Tableau (that supported connected apps), the authentication flow was performed inside the iframe. If you can’t use the new authentication flow, you can revert to the previous flow by setting the `iframeAuth` property on the view or Ask Data object, or the `iframe-auth` attribute on the component. Using the older flow doesn’t provide the error handling capability available with the 3.6 library and Tableau 2023.2, so you won’t be able to use the new `VizLoadError` event. To use the older authentication flow with the 3.6 library and Tableau 2023.2, add the `iframe-auth` attribute in the web component (or set the `iframeAuth` property on the Viz object). ``` ``` * * * ### Securely sign users out of embedded Tableau content In most cases, with connected apps (direct trust) and embedded views, when a user logs out of the webpage/application there really isn’t an issue with another user accessing the embedded content because users aren’t typically using a shared environment. However, if users access an embedded view in a shared environment (shared device/shared browser), you might need to securely sign them out between sessions. The problem is that when one user is done interacting with the embedded content, another user could still access the embedded content even if the first user logs out. The reason is because Tableau sets an `HttpOnly` session cookie when you first sign in. If the browser stays open, as in a shared environment, the session remains active until it times out and expires, or until the browser closes. To make sure that the current user is signed out, and to clear the session cookie, call the [Tableau REST API Sign Out](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_authentication.htm#sign_out) endpoint. Starting with the Tableau REST API version 3.27, the sign-out endpoint removes the cookie and ends the session. For example, to fix the issue, add JavaScript code to your application that calls the REST sign-out endpoint. The following example shows one way to sign out the user and to end the session. In the example, `viz` is the `TableauViz` object for the embedded view. The example signs the user out and also forces the `iframe` to reload, which clears the view for the next user. ``` // assumes the viz object has been declared for the Tableau view // Available in API_VERSION 3.27 or later fetch("https://{YOUR_TABLEAU_CLOUD_BASE_URL}/api/{API_VERSION}/auth/signout", { credentials: "include", method: "POST", headers: { "Content-Type": "application/json;charset=UTF-8", }, body: JSON.stringify({}) }) .then((response) => { if (response.ok) { console.log("logout is successful!"); } }) .then(() => { console.log("reload the iframe to clear the view"); const iframe = viz.shadowRoot?.querySelector('iframe'); requestAnimationFrame(() => { iframe.src = iframe.src; // defers the reload to after the current paint cycle }); }) .catch((error) => console.error("Error:", error)); ``` * * * ## More information - For the list of connected app error codes, see the following: - Direct trust - [Troubleshoot Connected Apps (Tableau Cloud)](https://help.tableau.com/current/online/en-us/connected_apps_troubleshoot.htm) or [Troubleshoot Connected Apps (Tableau Server)](https://help.tableau.com/current/server/en-us/connected_apps_troubleshoot.htm) - OAuth 2.0 trust - [Troubleshoot (Tableau Cloud)](https://help.tableau.com/current/online/en-us/connected_apps_eas.htm#troubleshoot) or [Troubleshoot (Tableau Server)](https://help.tableau.com/current/server/en-us/connected_apps_eas.htm#troubleshoot) - For general information about connected apps, see the following: - Tableau Cloud - [Configure Tableau Connected Apps](https://help.tableau.com/current/online/en-us/connected_apps.htm) - Tableau Server, [Configure Tableau Connected Apps (Windows)](https://help.tableau.com/current/server/en-us/connected_apps_eas.htm) - For information about setting up a connected app on Tableau Cloud or Tableau using the Tableau REST API, see [Connected App Methods](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_connected_app.htm). - For information about configuring a unified access token (using the Tableau Cloud Manager REST API), see [Unified Access Tokens](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html). - For sample code showing how you can construct the JWT, see the [connected-apps-jwt-samples](https://github.com/tableau/connected-apps-jwt-samples) repository on GitHub. - For information custom domains, see [Introducing Tableau Cloud Custom Domains](https://www.tableau.com/blog/introducing-tableau-cloud-custom-domains) and [Use a Custom Domain with Tableau Cloud](https://help.tableau.com/current/online/en-us/custom_domain.htm). #### On This Page - AuthoringViz # Interface AuthoringViz The interface for the top level Authoring Viz object. interface AuthoringViz { [debug](#debug)?: boolean; [height](#height)?: string | number; [hideCloseButton](#hideclosebutton)?: boolean; [hideEditInDesktopButton](#hideeditindesktopbutton)?: boolean; [iframeAttributeClass](#iframeattributeclass)?: string; [iframeAttributeLoading](#iframeattributeloading)?: string; [iframeAttributeStyle](#iframeattributestyle)?: string; [iframeAuth](#iframeauth)?: boolean; [onEditInDesktopButtonClicked](#oneditindesktopbuttonclicked)?: string; [onFirstInteractive](#onfirstinteractive)?: string; [onFirstVizSizeKnown](#onfirstvizsizeknown)?: string; [onWorkbookPublished](#onworkbookpublished)?: string; [onWorkbookPublishedAs](#onworkbookpublishedas)?: string; [onWorkbookReadyToClose](#onworkbookreadytoclose)?: string; [src](#src)?: null | string; [suppressDefaultEditBehavior](#suppressdefaulteditbehavior)?: boolean; [token](#token)?: string; [touchOptimize](#touchoptimize)?: boolean; [width](#width)?: string | number; [getCurrentSrcAsync](#getcurrentsrcasync-1)(): Promise; [getVizQLDataServiceSessionInfo](#getvizqldataservicesessioninfo-1)(): [VizQLDataServiceSessionInfo](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizQLDataServiceSessionInfo.html); [isAnalyticsAssistantAvailableAsync](#isanalyticsassistantavailableasync-1)(): Promise; [launchAnalyticsAssistantAsync](#launchanalyticsassistantasync-1)(): Promise; [resize](#resize-1)(): void; [setAuthToken](#setauthtoken-1)(token: string): void; } #### Hierarchy ([View Summary](https://help.tableau.com/current/api/embedding_api/en-us/reference/hierarchy.html#AuthoringViz)) - [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html) - [WebComponentLocalSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html) - AuthoringViz - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:119 ##### Index ### Methods [getCurrentSrcAsync](#getcurrentsrcasync) [getVizQLDataServiceSessionInfo](#getvizqldataservicesessioninfo) [isAnalyticsAssistantAvailableAsync](#isanalyticsassistantavailableasync) [launchAnalyticsAssistantAsync](#launchanalyticsassistantasync) [resize](#resize) [setAuthToken](#setauthtoken) ### Properties [debug?](#debug) [height?](#height) [hideCloseButton?](#hideclosebutton) [hideEditInDesktopButton?](#hideeditindesktopbutton) [iframeAttributeClass?](#iframeattributeclass) [iframeAttributeLoading?](#iframeattributeloading) [iframeAttributeStyle?](#iframeattributestyle) [iframeAuth?](#iframeauth) [onEditInDesktopButtonClicked?](#oneditindesktopbuttonclicked) [onFirstInteractive?](#onfirstinteractive) [onFirstVizSizeKnown?](#onfirstvizsizeknown) [onWorkbookPublished?](#onworkbookpublished) [onWorkbookPublishedAs?](#onworkbookpublishedas) [onWorkbookReadyToClose?](#onworkbookreadytoclose) [src?](#src) [suppressDefaultEditBehavior?](#suppressdefaulteditbehavior) [token?](#token) [touchOptimize?](#touchoptimize) [width?](#width) ## Methods ### getCurrentSrcAsync[](#getcurrentsrcasync) - getCurrentSrcAsync(): Promise[](#getcurrentsrcasync-1) Gets the visualization's current URL. #### Returns Promise - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:123 ### getVizQLDataServiceSessionInfo[](#getvizqldataservicesessioninfo) - getVizQLDataServiceSessionInfo(): [VizQLDataServiceSessionInfo](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizQLDataServiceSessionInfo.html)[](#getvizqldataservicesessioninfo-1) Gets the server session information for use with VizQL Data Service. The server session information contains the VizQL Server Session ID (X-Session-Id) and the Global Session Header (Global-Session-Header). #### Returns [VizQLDataServiceSessionInfo](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizQLDataServiceSessionInfo.html) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:165 ### isAnalyticsAssistantAvailableAsync[](#isanalyticsassistantavailableasync) - isAnalyticsAssistantAvailableAsync(): Promise[](#isanalyticsassistantavailableasync-1) Indicates whether the Analytics Assistant side pane is available. #### Returns Promise - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:159 ### launchAnalyticsAssistantAsync[](#launchanalyticsassistantasync) - launchAnalyticsAssistantAsync(): Promise[](#launchanalyticsassistantasync-1) Use this method to launch the Analytics Assistant side pane. You can use the `isAnalyticsAssistantAvailableAsync()` method to check if the Analytics Assistant is available for use. ``` const isAnalyticsAssistantAvailable = await viz.isAnalyticsAssistantAvailableAsync();if (isAnalyticsAssistantAvailable) { await viz.launchAnalyticsAssistantAsync();} ``` #### Returns Promise - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:154 ### resize[](#resize) - resize(): void[](#resize-1) Use this method to readjust the dimensions of the embedded viz in response to things like a window resize, device orientation change, or parent container resize. ``` window.addEventListener('resize', () => viz.resize());new ResizeObserver(() => viz.resize()).observe(viz.parentElement); ``` #### Returns void - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:141 ### setAuthToken[](#setauthtoken) - setAuthToken(token: string): void[](#setauthtoken-1) Provide an auth token for salesforce native mode #### Parameters - token: string #### Returns void - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:129 ## Properties ### `Optional`debug[](#debug) debug?: boolean Indicates whether the non-minified version of JavaScript is loaded. If specified (or set to true), the non-minified version is used for both the local component and the Tableau Server visualization (if enabled). If not specified (or set to false), the minified version of the JavaScript files are loaded. ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[debug](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#debug) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:50 ### `Optional`height[](#height) height?: string | number Represents height in pixels Can be any valid CSS size specifier. If not specified, defaults to the published height of the view. Inherited from [WebComponentLocalSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html).[height](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html#height) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:20 ### `Optional`hideCloseButton[](#hideclosebutton) hideCloseButton?: boolean Indicates whether the Close button is hidden or visible. If not set, defaults to false, meaning that the Close button is visible. ``` ``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[hideCloseButton](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#hideclosebutton) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:693 ### `Optional`hideEditInDesktopButton[](#hideeditindesktopbutton) hideEditInDesktopButton?: boolean Indicates whether the Edit in Desktop button is hidden or visible. If not specified, defaults to false, meaning that the Edit in Desktop button is visible. ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[hideEditInDesktopButton](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#hideeditindesktopbutton) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:457 ### `Optional`iframeAttributeClass[](#iframeattributeclass) iframeAttributeClass?: string The value of the 'class' attribute of the embedded iframe providing access to any custom selectors defined in the `` child tag. ```

.red-border { border: 1px solid red; }

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[iframeAttributeClass](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#iframeattributeclass) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:101 ### `Optional`iframeAttributeLoading[](#iframeattributeloading) iframeAttributeLoading?: string The value of the 'loading' attribute of the embedded iframe. See: [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#loading](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#loading) ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[iframeAttributeLoading](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#iframeattributeloading) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:74 ### `Optional`iframeAttributeStyle[](#iframeattributestyle) iframeAttributeStyle?: string The value of the 'style' attribute of the embedded iframe. ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[iframeAttributeStyle](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#iframeattributestyle) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:85 ### `Optional`iframeAuth[](#iframeauth) iframeAuth?: boolean Indicates whether to use the old auth mechanism for authentication which happens inside the iframe. If specified, VizLoadErrorEvents triggered due to auth failures will not be thrown. ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[iframeAuth](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#iframeauth) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:62 ### `Optional`onEditInDesktopButtonClicked[](#oneditindesktopbuttonclicked) onEditInDesktopButtonClicked?: string An event raised when the user clicks on the Edit In Desktop Button. You can use this event type with TableauViz objects. ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[onEditInDesktopButtonClicked](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#oneditindesktopbuttonclicked) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:477 ### `Optional`onFirstInteractive[](#onfirstinteractive) onFirstInteractive?: string An event raised when the Viz object first becomes interactive. This is only raised once. ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[onFirstVizSizeKnown](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#onfirstvizsizeknown) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:487 ### `Optional`onWorkbookPublished[](#onworkbookpublished) onWorkbookPublished?: string An event raised when the workbook has been published. This notification is sent when using embedded web authoring functionality. ``` ``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[onWorkbookPublished](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#onworkbookpublished) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:701 ### `Optional`onWorkbookPublishedAs[](#onworkbookpublishedas) onWorkbookPublishedAs?: string An event raised when "publish as" is successful. This notification is sent when using embedded web authoring functionality. ``` ``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[onWorkbookPublishedAs](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#onworkbookpublishedas) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:709 ### `Optional`onWorkbookReadyToClose[](#onworkbookreadytoclose) onWorkbookReadyToClose?: string An event raised when the workbook is ready to close. This notification is sent when using embedded web authoring functionality. ``` ``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[onWorkbookReadyToClose](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#onworkbookreadytoclose) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:717 ### `Optional`src[](#src) src?: null | string The viz src Inherited from [WebComponentLocalSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html).[src](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html#src) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:8 ### `Optional`suppressDefaultEditBehavior[](#suppressdefaulteditbehavior) suppressDefaultEditBehavior?: boolean Indicates whether the default edit behavior is suppressed. If not specified, defaults to false, meaning that the default edit behavior is not suppressed. ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[suppressDefaultEditBehavior](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#suppressdefaulteditbehavior) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:468 ### `Optional`token[](#token) token?: string The token used for authorization ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[token](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#token) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:37 ### `Optional`touchOptimize[](#touchoptimize) touchOptimize?: boolean Indicates whether to touch optimize viz controls. ```

``` Inherited from [VizAuthoringSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html).[touchOptimize](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/VizAuthoringSettings.html#touchoptimize) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/VizInterfaces.ts:446 ### `Optional`width[](#width) width?: string | number Represents width in pixels Can be any valid CSS size specifier. If not specified, defaults to the published width of the view. Inherited from [WebComponentLocalSettings](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html).[width](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/WebComponentLocalSettings.html#width) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/WebComponentInterfaces.ts:14 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Methods [getCurrentSrcAsync](#getcurrentsrcasync)[getVizQLDataServiceSessionInfo](#getvizqldataservicesessioninfo)[isAnalyticsAssistantAvailableAsync](#isanalyticsassistantavailableasync)[launchAnalyticsAssistantAsync](#launchanalyticsassistantasync)[resize](#resize)[setAuthToken](#setauthtoken) Properties [debug](#debug)[height](#height)[hideCloseButton](#hideclosebutton)[hideEditInDesktopButton](#hideeditindesktopbutton)[iframeAttributeClass](#iframeattributeclass)[iframeAttributeLoading](#iframeattributeloading)[iframeAttributeStyle](#iframeattributestyle)[iframeAuth](#iframeauth)[onEditInDesktopButtonClicked](#oneditindesktopbuttonclicked)[onFirstInteractive](#onfirstinteractive)[onFirstVizSizeKnown](#onfirstvizsizeknown)[onWorkbookPublished](#onworkbookpublished)[onWorkbookPublishedAs](#onworkbookpublishedas)[onWorkbookReadyToClose](#onworkbookreadytoclose)[src](#src)[suppressDefaultEditBehavior](#suppressdefaulteditbehavior)[token](#token)[touchOptimize](#touchoptimize)[width](#width) # Basic Embedding The easiest way to embed Tableau views into web applications is to use the embed code that is generated when you click the **Share** button on a published view. You simply copy the code and place it in your HTML page. Starting with Tableau 2021.4, the Embedding API v3 makes it almost as easy by giving you the option of simply adding a web component to your web page. Starting in Tableau 2022.3, Tableau Server, Tableau Cloud, and Tableau Public use the Embedding API v3 web component for the **Embed Code** option (available from **Share** button on the toolbar). The good news is that embedding views using the Embedding API v3 code is now even easier. You can use the Embedding API v3 in Tableau 2021.4 and later. For the Embedding API v3, there are two ways to initializing the API and embed the visualization in your web application: - Use the web component (``) in your HTML code. - Use JavaScript to create the `TableauViz` object. You can also take a hybrid approach and combine these two ways. This topic will show you how you can use these options. For information about editing embedded views, see [Embed Web Authoring](/current/api/embedding_api/en-us/docs/embedding_api_web_authoring.html). * * * ## Use the `tableau-viz` web component for basic embedding The Tableau Embedding API v3 makes embedding a view in your web page or application easy to do, without a lot of JavaScript coding. You just link to the Embedding API library and then add a web component to your HTML code, much like you would any other HTML element. ### Link to the Embedding API library Starting with Tableau 2021.4, the Embedding API v3 is available on Tableau Server, Tableau Cloud, and Tableau Public. In most cases, you should use the version of the Embedding API library that is hosted on the Tableau instance that is serving the view you’re embedding. If you use the file from one of these locations, you can link to the file `tableau.embedding.3.latest.min.js`, which will always point to the latest release of the library. The library is a JavaScript ES6 module. To use the library in your web application, you need to set the `type` attribute to `module` in the ` ``` The library is also hosted on the Tableau CDN, `https://embedding.tableauusercontent.com/`. If you use the library from the CDN, you need to link to a specific release of the file. For example, to use version 3.1.0 of the library, you would include the following in your HTML code: ``` ``` The file, `tableau.embedding.3.latest.min.js`, is only available on Tableau Server, Tableau Cloud, and Tableau Public. For more information about the library file, see [Access the Embedding API](/current/api/embedding_api/en-us/docs/embedding_api_get.html). ### Add the `tableau-viz` component to your HTML page After you link to the library, you can use Tableau Embedding API. Using a `` web component is the simplest way to embed a view into a page and to initialize the Embedding API. You can use the component to configure how you want to initialize the display of the view, by adding attributes, see [Configure Embedding Objects and Components](/current/api/embedding_api/en-us/docs/embedding_api_configure.html). The basic structure of the `` web component is as follows: ``` ``` The `src` attribute specifies the URL of the view on Tableau Server. The best way to get the URL is to click the **Share** button on the Tableau toolbar and then use the **Copy Link**. The `id` attribute identifies the instance of the web component. You will need this `id` if you want to access the view programmatically after the initial loading. For more information, see [Interact with the View](/current/api/embedding_api/en-us/docs/embedding_api_interact.html). For security in your embedded application, Tableau requires that you use the Hypertext Transfer Protocol Secure (HTTPS) when you specify the URL. HTTPS helps protects privacy by encyrypting communication. **Note:** Starting in Tableau 2022.3, Tableau Server, Tableau Cloud, and Tableau Public will use the Embedding API v3 web component for the **Embed Code** option (available from the **Share** button on the toolbar). The `` component replaces the [JavaScript API v1 code previously used.](https://help.tableau.com/current/pro/desktop/en-us/embed_code.htm) If you have web pages that use **Embed Code**, you should update them to use the new initialization method. Be sure to include a link to the Embedding API v3 library. For information about how you can configure the `` component, see [Configure Embedding Objects and Components](/current/api/embedding_api/en-us/docs/embedding_api_configure.html). * * * ## Use JavaScript to initialize the API and embed the view In some instances, you might prefer to configure and initialize the embedded view using JavaScript and the `TableauViz` object, rather than using the `` web component. The first step is to create an `

` to contain the embedded view in your HTML code. In this respect, this is similar to what you do to embed a view using the JavaScript API v2. You also need to give the `

` an identifier (say, `tableauViz`) so that you can specify that element when you append the embedded view. This is important because the view is not rendered until you add it to the DOM. ### HTML code ```

``` 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`. ``` ``` ### JavaScript code for embedding a TableauViz object In your JavaScript code, you need to import the `TableauViz` 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 view and other properties and methods supported by the object (see [Configure Embedding Objects and Components](/current/api/embedding_api/en-us/docs/embedding_api_configure.html). To simplify your code and improve load times, import just the classes you need, for example `TableauViz` to create the JavaScript object and `TableauEventType` to set an event listener. ``` import { TableauViz, TableauEventType, } from 'https://my-server/javascripts/api/tableau.embedding.3.latest.min.js'; ``` For example, the following code shows how you might embed a view. In this instance, the toolbar is hidden. The example shows how you could add an event listener. In this case, the code adds a `MarkSelectionChanged` event, which is triggered whenever the marks selected in the view change. Elsewhere in your code, you would need to add a `handleMarkSelection()` method to handle the event. 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). ``` import { TableauViz, TableauEventType, } from 'https://my-server/javascripts/api/tableau.embedding.3.latest.min.js'; const viz = new TableauViz(); viz.src = 'https://my-server/views/my-workbook/my-view'; viz.toolbar = 'hidden'; viz.addEventListener(TableauEventType.MarkSelectionChanged, handleMarkSelection); document.getElementById('tableauViz').appendChild(viz); /* Methods */ function handleMarkSelection() { alert('Mark(s) selected!'); // code to handle the mark selection goes here } ``` * * * **Important:** 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`. If you import the file as text, the Embedding API library fails to load. ``` ``` * * * For information about how you can configure the `TableauViz` object see [Configure Embedding Objects and Components](/current/api/embedding_api/en-us/docs/embedding_api_configure.html). * * * ## Combine JavaScript and the `tableau-viz` web component to embed the view Some people might prefer a hybrid approach, combining the advantage of using a semantic HTML element with the flexibility and efficiency of JavaScript. In this case, you add a `` web component to your HTML page. But instead of specifying all of the attributes, the URL, toolbar options, etc., you just specify the `` 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. ``` ... ... ``` In your JavaScript code, create the `viz` object from the HTML element, and then use the `viz` object to configure the embedded view. ``` const viz = document.getElementById("tableauViz"); viz.src = url; ``` This is similar to the process you take when you [Interact With the View](/current/api/embedding_api/en-us/docs/embedding_api_interact.html) created using the web component. * * * ## Example of basic embedding using the `tableau-viz` web component Here’s the code that shows basic embedding: ``` ``` Here’s what it looks like when you use the code to embed the viz on a web page: * * * ## What’s Next? If you want to add interaction with the Tableau viz, so that users can filter or change the view based upon HTML controls you add to your web page, . For information about the attributes and properties you can set on the embedded web component or JavaScript object, see [Configure Embedding Objects and Components](/current/api/embedding_api/en-us/docs/embedding_api_configure.html). #### On This Page - CategoricalDomain # Interface CategoricalDomain The domain of a categorical filter interface CategoricalDomain { [type](#type): [FilterDomainType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterDomainType.html); [values](#values): [DataValue](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/DataValue.html)\[\]; } - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:250 ##### Index ### Properties [type](#type) [values](#values) ## Properties ### `Readonly`type[](#type) type: [FilterDomainType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterDomainType.html) #### Returns[](#returns) the domain type (relevant, all) - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:254 ### `Readonly`values[](#values) values: [DataValue](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/DataValue.html)\[\] #### Returns[](#returns-1) the list of values in the domain of the filter - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:258 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Properties [type](#type)[values](#values) - CategoricalFilter # Interface CategoricalFilter A Categorical Filter interface CategoricalFilter { [appliedValues](#appliedvalues): [DataValue](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/DataValue.html)\[\]; [fieldId](#fieldid): string; [fieldName](#fieldname): string; [filterType](#filtertype): [FilterType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterType.html); [isAllSelected](#isallselected)?: boolean; [isExcludeMode](#isexcludemode): boolean; [worksheetName](#worksheetname): string; [getAppliedWorksheetsAsync](#getappliedworksheetsasync-1)(): Promise; [getDomainAsync](#getdomainasync-1)(domainType?: [FilterDomainType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterDomainType.html)): Promise<[CategoricalDomain](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/CategoricalDomain.html)\>; [getFieldAsync](#getfieldasync-1)(): Promise<[Field](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Field.html)\>; [setAppliedWorksheetsAsync](#setappliedworksheetsasync-1)(applyToWorksheets: string\[\]): Promise; } #### Hierarchy ([View Summary](https://help.tableau.com/current/api/embedding_api/en-us/reference/hierarchy.html#CategoricalFilter)) - [Filter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html) - CategoricalFilter - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:65 ##### Index ### Methods [getAppliedWorksheetsAsync](#getappliedworksheetsasync) [getDomainAsync](#getdomainasync) [getFieldAsync](#getfieldasync) [setAppliedWorksheetsAsync](#setappliedworksheetsasync) ### Properties [appliedValues](#appliedvalues) [fieldId](#fieldid) [fieldName](#fieldname) [filterType](#filtertype) [isAllSelected?](#isallselected) [isExcludeMode](#isexcludemode) [worksheetName](#worksheetname) ## Methods ### getAppliedWorksheetsAsync[](#getappliedworksheetsasync) - getAppliedWorksheetsAsync(): Promise[](#getappliedworksheetsasync-1) #### Returns Promise the list of worksheet names that have the filter applied. Inherited from [Filter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html).[getAppliedWorksheetsAsync](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html#getappliedworksheetsasync) - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:49 ### getDomainAsync[](#getdomainasync) - getDomainAsync(domainType?: [FilterDomainType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterDomainType.html)): Promise<[CategoricalDomain](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/CategoricalDomain.html)\>[](#getdomainasync-1) #### Parameters - `Optional`domainType: [FilterDomainType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterDomainType.html) #### Returns Promise<[CategoricalDomain](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/CategoricalDomain.html)\> a promise containing the categorical domain for the filter. Note if a filter contains multiple fields (such as a filter action with multiple fields), the values array in the returned CategoricalDomain ([CategoricalDomain.values](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/CategoricalDomain.html#values)) will be empty. If there are multiple fields in the filter, the results need to be represented by a table, which is not currently supported. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:91 ### getFieldAsync[](#getfieldasync) - getFieldAsync(): Promise<[Field](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Field.html)\>[](#getfieldasync-1) #### Returns Promise<[Field](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Field.html)\> a promise containing the field for the filter. Inherited from [Filter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html).[getFieldAsync](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html#getfieldasync) - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:43 ### setAppliedWorksheetsAsync[](#setappliedworksheetsasync) - setAppliedWorksheetsAsync(applyToWorksheets: string\[\]): Promise[](#setappliedworksheetsasync-1) Applies the filter to the specified list of worksheets. If the worksheet(s) do not exist or do not contain the field in their data sources, an exception is thrown. #### Parameters - applyToWorksheets: string\[\] list of worksheets to apply the filter on #### Returns Promise the list of worksheet names that have the filter applied Inherited from [Filter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html).[setAppliedWorksheetsAsync](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html#setappliedworksheetsasync) - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:59 ## Properties ### `Readonly`appliedValues[](#appliedvalues) appliedValues: [DataValue](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/DataValue.html)\[\] #### Returns[](#returns) A list of values applied to this categorical filter. Notice that if this is a dependent filter, the current relavent values can be fetched by calling `getDomainAsync(tableau.FilterDomainType.Relevant)`. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:78 ### `Readonly`fieldId[](#fieldid) fieldId: string #### Returns[](#returns-1) The id of the field being filtered. Inherited from [Filter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html).[fieldId](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html#fieldid) - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:37 ### `Readonly`fieldName[](#fieldname) fieldName: string #### Returns[](#returns-2) The name of the field being filtered. Note that this is the caption as shown in the UI, and not the actual database field name. Inherited from [Filter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html).[fieldName](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html#fieldname) - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:31 ### `Readonly`filterType[](#filtertype) filterType: [FilterType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterType.html) #### Returns[](#returns-3) The type of the filter. Inherited from [Filter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html).[filterType](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html#filtertype) - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:25 ### `Optional` `Readonly`isAllSelected[](#isallselected) isAllSelected?: boolean #### Returns[](#returns-4) True if all the values are selected for this filter. When 'All' is selected, appliedValues returns an empty list. This field is available in Tableau 2019.2 or later - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:72 ### `Readonly`isExcludeMode[](#isexcludemode) isExcludeMode: boolean #### Returns[](#returns-5) True if this filter is an exclude filter, false if an include filter. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:83 ### `Readonly`worksheetName[](#worksheetname) worksheetName: string #### Returns[](#returns-6) The parent worksheet. Inherited from [Filter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html).[worksheetName](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/Filter.html#worksheetname) - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/FilterInterfaces.ts:20 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Methods [getAppliedWorksheetsAsync](#getappliedworksheetsasync)[getDomainAsync](#getdomainasync)[getFieldAsync](#getfieldasync)[setAppliedWorksheetsAsync](#setappliedworksheetsasync) Properties [appliedValues](#appliedvalues)[fieldId](#fieldid)[fieldName](#fieldname)[filterType](#filtertype)[isAllSelected](#isallselected)[isExcludeMode](#isexcludemode)[worksheetName](#worksheetname) - CategoricalPulseFilter # Interface CategoricalPulseFilter A Pulse Categorical Filter interface CategoricalPulseFilter { [appliedValues](#appliedvalues): [PulseFieldValueArray](https://help.tableau.com/current/api/embedding_api/en-us/reference/types/PulseFieldValueArray.html); [fieldName](#fieldname): string; [filterType](#filtertype): [FilterType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterType.html); [getDomainAsync](#getdomainasync): ( searchTerm?: string, pageSize?: number, nextPageToken?: string, domainType?: [FilterDomainType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterDomainType.html), ) \=> Promise<[PulseCategoricalDomain](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseCategoricalDomain.html)\>; [isAllSelected](#isallselected)?: boolean; [isExcludeMode](#isexcludemode): boolean; [metricId](#metricid): string; } #### Hierarchy ([View Summary](https://help.tableau.com/current/api/embedding_api/en-us/reference/hierarchy.html#CategoricalPulseFilter)) - [PulseFilter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseFilter.html) - CategoricalPulseFilter - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/PulseInterfaces.ts:319 ##### Index ### Properties [appliedValues](#appliedvalues) [fieldName](#fieldname) [filterType](#filtertype) [getDomainAsync](#getdomainasync) [isAllSelected?](#isallselected) [isExcludeMode](#isexcludemode) [metricId](#metricid) ## Properties ### `Readonly`appliedValues[](#appliedvalues) appliedValues: [PulseFieldValueArray](https://help.tableau.com/current/api/embedding_api/en-us/reference/types/PulseFieldValueArray.html) A list of values applied to this categorical filter. Notice that if the Pulse metric has a definition filter, the current relevant values can be fetched by calling `getDomainAsync(FilterDomainType.Relevant)`. - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/PulseInterfaces.ts:325 ### fieldName[](#fieldname) fieldName: string The name of the field being filtered. Note that this is the caption as shown in the UI, and not the actual database field name. Inherited from [PulseFilter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseFilter.html).[fieldName](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseFilter.html#fieldname) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/PulseInterfaces.ts:303 ### filterType[](#filtertype) filterType: [FilterType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterType.html) The type of the filter. Inherited from [PulseFilter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseFilter.html).[filterType](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseFilter.html#filtertype) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/PulseInterfaces.ts:308 ### getDomainAsync[](#getdomainasync) getDomainAsync: ( searchTerm?: string, pageSize?: number, nextPageToken?: string, domainType?: [FilterDomainType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterDomainType.html), ) \=> Promise<[PulseCategoricalDomain](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseCategoricalDomain.html)\> Gets the domain of a categorical filter. #### Type declaration - - ( searchTerm?: string, pageSize?: number, nextPageToken?: string, domainType?: [FilterDomainType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterDomainType.html), ): Promise<[PulseCategoricalDomain](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseCategoricalDomain.html)\> - #### Parameters - `Optional`searchTerm: string The term to search for in the domain. - `Optional`pageSize: number The maximum number of values to return. Ignored when nextPageToken is not provided. - `Optional`nextPageToken: string The next page token returned by Pulse when additional values are available. - `Optional`domainType: [FilterDomainType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/FilterDomainType.html) The domain type of the filter. #### Returns Promise<[PulseCategoricalDomain](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseCategoricalDomain.html)\> A promise containing the categorical domain for the filter. - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/PulseInterfaces.ts:347 ### `Optional` `Readonly`isAllSelected[](#isallselected) isAllSelected?: boolean True if all the values are selected for this filter. When 'All' is selected, appliedValues returns an empty list. - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/PulseInterfaces.ts:336 ### `Readonly`isExcludeMode[](#isexcludemode) isExcludeMode: boolean True if this filter is an exclude filter, false if an include filter. - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/PulseInterfaces.ts:330 ### metricId[](#metricid) metricId: string The Pulse metric ID. Inherited from [PulseFilter](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseFilter.html).[metricId](https://help.tableau.com/current/api/embedding_api/en-us/reference/interfaces/PulseFilter.html#metricid) - Defined in packages/api-external-contract-js/src/ExternalContract/Embedding/PulseInterfaces.ts:313 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Properties [appliedValues](#appliedvalues)[fieldName](#fieldname)[filterType](#filtertype)[getDomainAsync](#getdomainasync)[isAllSelected](#isallselected)[isExcludeMode](#isexcludemode)[metricId](#metricid) - CategoricalValue # Type Alias CategoricalValue CategoricalValue: string | string\[\] Categorical values for selection. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/SelectionInterfaces.ts:66 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark - ClassNameKey # Enumeration ClassNameKey - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:25 ##### Index ### Enumeration Members [ColumnDividers](#columndividers) [DashboardTitle](#dashboardtitle) [Pane](#pane) [RowDividers](#rowdividers) [StoryTitle](#storytitle) [Tooltip](#tooltip) [Worksheet](#worksheet) [WorksheetTitle](#worksheettitle) ## Enumeration Members ### ColumnDividers[](#columndividers) ColumnDividers: "tableau-column-dividers" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:33 ### DashboardTitle[](#dashboardtitle) DashboardTitle: "tableau-dashboard-title" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:30 ### Pane[](#pane) Pane: "tableau-pane" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:31 ### RowDividers[](#rowdividers) RowDividers: "tableau-row-dividers" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:32 ### StoryTitle[](#storytitle) StoryTitle: "tableau-story-title" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:29 ### Tooltip[](#tooltip) Tooltip: "tableau-tooltip" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:28 ### Worksheet[](#worksheet) Worksheet: "tableau-worksheet" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:27 ### WorksheetTitle[](#worksheettitle) WorksheetTitle: "tableau-worksheet-title" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:26 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Enumeration Members [ColumnDividers](#columndividers)[DashboardTitle](#dashboardtitle)[Pane](#pane)[RowDividers](#rowdividers)[StoryTitle](#storytitle)[Tooltip](#tooltip)[Worksheet](#worksheet)[WorksheetTitle](#worksheettitle) - Column # Interface Column interface Column { [dataType](#datatype): [DataType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/DataType.html); [fieldId](#fieldid): string; [fieldName](#fieldname): string; [index](#index): number; [isReferenced](#isreferenced): boolean; } - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/DataTableInterfaces.ts:4 ##### Index ### Properties [dataType](#datatype) [fieldId](#fieldid) [fieldName](#fieldname) [index](#index) [isReferenced](#isreferenced) ## Properties ### `Readonly`dataType[](#datatype) dataType: [DataType](https://help.tableau.com/current/api/embedding_api/en-us/reference/enums/DataType.html) #### Returns[](#returns) The data type of the column. Possible values are float, integer, string, boolean, date, datetime and spatial - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/DataTableInterfaces.ts:26 ### `Readonly`fieldId[](#fieldid) fieldId: string #### Returns[](#returns-1) The fieldId of the field in the column. In summary data, this includes the aggregation. The fieldId is not stable across replacing data sources. For example after replacing the data source \[Clipboard\_20210305T164000\].\[sum:Sales:qk\] could become \[federated.12usuoq1171o1b1ebdyh60fjnev1\].\[sum:Sales:qk\]. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/DataTableInterfaces.ts:20 ### `Readonly`fieldName[](#fieldname) fieldName: string #### Returns[](#returns-2) The name of the field in the column. In summary data, this includes the aggregation. The summary data field name is not stable across languages. For example, in an English version of Tableau, the field name might be SUM(Sales). In French, this would be SOMME(Sales). - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/DataTableInterfaces.ts:10 ### `Readonly`index[](#index) index: number #### Returns[](#returns-3) The number of rows in the returned data. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/DataTableInterfaces.ts:36 ### `Readonly`isReferenced[](#isreferenced) isReferenced: boolean #### Returns[](#returns-4) Whether the column data is referenced in the visualization. - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/DataTableInterfaces.ts:31 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Properties [dataType](#datatype)[fieldId](#fieldid)[fieldName](#fieldname)[index](#index)[isReferenced](#isreferenced) - ColumnType # Enumeration ColumnType - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:19 ##### Index ### Enumeration Members [Continuous](#continuous) [Discrete](#discrete) [Unknown](#unknown) ## Enumeration Members ### Continuous[](#continuous) Continuous: "continuous" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:21 ### Discrete[](#discrete) Discrete: "discrete" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:20 ### Unknown[](#unknown) Unknown: "unknown" - Defined in packages/api-external-contract-js/src/ExternalContract/Shared/Namespaces/Tableau.ts:22 ### Settings Member Visibility - Protected - Inherited - External ThemeOSLightDark ### On This Page Enumeration Members [Continuous](#continuous)[Discrete](#discrete)[Unknown](#unknown) # Configure Embedding Objects and Components The Embedding API v3 provides a rich set of properties that you can apply to the embedding view or embedded web authoring view. These properties can control the device layout and dimensions of the view, or whether the buttons and the toolbar are hidden or visible. You can set properties during initialization, or later interactively, by accessing the JavaScript `TableauViz` or `TableauAuthoringViz` object. * * * ## How to configure the `TableauViz` and `TableauAuthoringViz` objects and components To configure the embedded viz, you can use a set of HTML attributes on the `` and `` web components, or as JavaScript (JS) properties on the corresponding `TableauViz` and `TableauAuthoringViz` JavaScript objects. For HTML attributes that accept a value, such as `width`, `height`, and `device`, the syntax is `=""`. For Boolean properties, such as `hide-tabs`, `hide-close-button`, or `disable-url-actions`, you can either include the flag to effectively set it to true, or omit it to effectively set it to false. The values of Boolean properties are ignored. For example, if you were to add `hide-tabs="false"`, this flag actually sets the `hide-tabs` value to true, because the presence of the attribute sets it to true even if the value is false. Some attributes and properties apply to both embedded views and embedded authoring views. ### Example `tableau-viz` component configurations The following example shows how you can specify options to initialize the viz by setting attributes on the `` element: ```HTML ``` ### Example `tableau-authoring-viz` component configuration The following example shows how you can specify options to initialize the viz by setting attributes on the `` element: ```HTML ``` ## Table of properties and values for embedded objects and components The following table lists the properties you can add to the `` and `` web components, or as JavaScript (JS) properties on the corresponding `TableauViz` and `TableauAuthoringViz` JavaScript objects. | HTML Property | JS Property | Accepted Values | Description | Applies to | | --- | --- | --- | --- | --- | | src | Viz.src | string | Specifies the URL of the view. For security, always use HTTPS when you specify the URL. | ``, `` | | hide-tabs | Viz.hideTabs | boolean | Indicates whether the tabs are hidden or shown. | `` | | toolbar | Viz.toolbar | “top”, “bottom”, “hidden” | Indicates the position of the toolbar or if it should be hidden | `` | | height | Viz.height | (e.g. “800px”) | Can be any valid CSS size specifier. If not specified, defaults to the published height of the view. See [Size of the embedded view](#size-of-the-embedded-view). | ``, `` | | width | Viz.width | (e.g. “800px”) | Can be any valid CSS size specifier. If not specified, defaults to the published width of the view. See [Size of the embedded view](#size-of-the-embedded-view). | ``, `` | | device | Viz.device | “default”, “desktop”, “tablet”, or “phone” | Specifies a device layout for a dashboard, if it exists. If not specified, defaults to loading a layout based on the smallest dimension of the hosting `iframe` element. | `` | | instance-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 doesn’t refer to an existing visualization, the cloned version is derived from the original visualization. | `` | | disable-url-actions | Viz.disableUrlActions | boolean | Indicates whether to suppress the execution of URL actions. This option doesn’t prevent the URL action event from being raised. | `` | | hide-close-button | Viz.hideCloseButton | boolean | Indicates whether the **Close** button is shown or hidden. If not specified, defaults to `false` (the button is shown). This property also includes the “File/Close” menu item. | `` | | hide-edit-button | Viz.hideEditButton | boolean | Indicates whether the **Edit** button is shown or hidden. If not specified, defaults to `false` (the button is shown). | `` | | hide-edit-in-desktop-button | Viz.hideEditInDesktopButton | boolean | Indicates whether the **Edit in Desktop** button is shown or hidden. If not specified, defaults to `false` (the button is shown). | ``, `` | | iframe attributes | | | See [iframe attributes](#add-iframe-attributes). | ``, ``, `` | | suppress-default-edit-behavior | Viz.suppressDefaultEditBehavior | boolean | Indicates whether the default edit behavior should be suppressed. If not specified, defaults to `false` (the default edit behavior is preserved). When set to true, this property suppresses what is normally done when the **Close** button, **Edit** button, or **Edit in Desktop** buttons are clicked. | ``, `` | | token | Viz.token | JSON Web Token | Holds the credentials and permissions. Only used for connected apps or external authorization services (EAS). See [Authentication and Embedded Views](/current/api/embedding_api/en-us/docs/embedding_api_auth.html). Not used for passwords or personal access tokens. | ``, ``, `` | > _Note:_ When adding properties to the `` or `` components, use the HTML Property name. Use the JS Property names for the `TableauViz` and `TableauAuthoringViz` objects. * * * ### Filter element for the `tableau-viz` web component In addition to the attributes shown in the table for the web components, you can also apply a `` element to the `` web component to filter the view during initialization. The `` element has two attributes: the `field` and its `value`. ``` ``` For more information about applying filters, see [Filter during initialization](/current/api/embedding_api/en-us/docs/embedding_api_filter.html#filtering-during-initialization). ### Parameter element for the `tableau-viz` web component In addition to the attributes shown in the table for the `` web component, you can also apply a `` element to the web component during initialization. The `` element has two attributes: the `name` and its `value`. ``` ``` The parameter settings take effect at startup. Also, the Embedding API v3 library supports the methods `Workbook.getParametersAsync()` and `Workbook.changeParameterValueAsync()`. For more information, see \[Use Parameters in Embedded V `and` \` web components In addition to the attributes shown in the table for the `` and `` web components, you can also apply a `` element to the web component during initialization. The `` element allows you to pass parameters to the viz that aren’t supported by the Embedding API, but are supported in Tableau. The `` has two attributes: the `name` and its `value`. The parameter settings take effect at startup. The custom parameters can be used to add URL parameters, as listed under [Embed Code Parameters for Views](https://help.tableau.com/current/pro/desktop/en-us/embed_list.htm#URL_params) for prior versions of embedding. For example, you could use custom parameters to suppress tooltips (`:tooltip`), or to hide the Share (`:showShareOptions`) or Data Details (`:dataDetails`) buttons in the toolbar. Some of these URL parameters might not work, or might not be supported in the future. ``` ``` For more information, see [About custom parameters](/current/api/embedding_api/en-us/docs/embedding_api_parameters.html#about-custom-parameters). **Note:** The attributes you place on the web component or viz object on the client are made available to the browser in order to render the embedded visualization. These attributes don't affect security. Tableau secures content by way of authentication and user permissions. If a user can't be authenticated and doesn't have the correct permissions the content is inaccessible behind a login screen. * * * ### Add `iframe` attributes The Tableau Embedding API provides some attributes that you can apply to the iframe element. You can use these attributes to customize the border that surrounds the Tableau view. You can also specify when the content of the iframe is loaded, to improve page load times and responsiveness. | HTML Property | JS Property | Accepted Values | Description | Applies to | | --- | --- | --- | --- | --- | | iframe-attribute-class | Viz.iframeAttributeClass | string | The value of the ‘class’ attribute of the embedded iframe providing access to any custom selectors defined in the `` child tag. See [`iframe-attr-class`](/current/api/embedding_api/en-us/reference/interfaces/Viz.html#iframeattributeclass). | ``, ``, `` | | iframe-attr-loading | Viz.iframeAttributeLoading | string | Specifies the loading attribute of the embedded `