Analytics Embedding SDK

Starting in July ‘26, this version is no longer supported. You must use v2.0. The back-end Lightning Out support has upgraded and isn’t compatible with this version of the SDK.

Important

Use the Analytics Embedding SDK to embed Tableau Next analytical components in any web page. This SDK supports typescript, javascript and HTML formats.

This version of the SDK is compatible with Salesforce API v65.0 and above.

Install

1npm install @salesforce/analytics-embedding-sdk --save

Usage

Note: The orgUrl parameter must be the Lightning URL (e.g., https://yourorg.lightning.force.com), not the my.salesforce.com domain URL.

TypeScript

1import {AnalyticsDashboard, initializeAnalyticsSdk, type AnalyticsSdkConfig} from '@salesforce/analytics-embedding-sdk';
2
3const config: AnalyticsSdkConfig = {
4   authCredential: "<%- auth-credential %>",
5   orgUrl: "<%- org_url %>" // Must be Lightning URL
6};
7await initializeAnalyticsSdk(config);
8
9// parentIdOrElement is the target container (ID or element) and idOrApiName is the identifier or API name of the component to embed.
10const dashboard: AnalyticsDashboard = new AnalyticsDashboard({parentIdOrElement: 'embed-here', idOrApiName: 'My_Sales_Dashboard'});
11dashboard.render();

JavaScript

1import { initializeAnalyticsSdk, AnalyticsDashboard } from "@salesforce/analytics-embedding-sdk";
2
3const config = {
4  authCredential: "<%- auth-credential %>",
5  orgUrl: "<%- org_url %>", // Must be Lightning URL
6};
7await initializeAnalyticsSdk(config);
8
9// parentIdOrElement is the target container (ID or element) and idOrApiName is the identifier or API name of the component to embed.
10const dashboard = new AnalyticsDashboard({
11  parentIdOrElement: "embed-here",
12  idOrApiName: "My_Sales_Dashboard",
13});
14dashboard.render();

HTML

1<!DOCTYPE html>
2<html>
3  <head>
4    <script type="module">
5      import { initializeAnalyticsSdk } from "@salesforce/analytics-embedding-sdk";
6
7      const config = {
8        authCredential: "<%- auth-credential %>",
9        orgUrl: "<%- org_url %>", // Must be Lightning URL
10      };
11
12      await initializeAnalyticsSdk({
13        authCredential: "<%- auth-credential %>",
14        orgUrl: "<%- org_url %>", // Must be Lightning URL
15      });
16    </script>
17  </head>
18  <body>
19    <analytics-dashboard id-or-api-name="My_Sales_Dashboard" height="500px"> </analytics-dashboard>
20  </body>
21</html>

Multi-org Support

The SDK supports embedding components from multiple Salesforce orgs in a single application. Use orgConfigs instead of a single orgUrl and authCredential:

1import {
2  initializeAnalyticsSdk,
3  AnalyticsDashboard,
4  AnalyticsVisualization,
5} from "@salesforce/analytics-embedding-sdk";
6
7// Initialize with multiple orgs
8const initPayload = {
9  orgConfigs: [
10    {
11      // Lightning URL required
12      orgUrl: "https://org1.lightning.force.com",
13      authCredential: "https://org1-frontdoor.salesforce.com/...",
14    },
15    {
16      // Lightning URL required
17      orgUrl: "https://org2.lightning.force.com",
18      authCredential: "https://org2-frontdoor.salesforce.com/...",
19    },
20  ],
21};
22
23const response = await initializeAnalyticsSdk(initPayload);
24
25// Embed components from different orgs - always specify orgUrl
26const dashboard = new AnalyticsDashboard({
27  parentIdOrElement: "container1",
28  idOrApiName: "Dashboard1",
29  // Required for multi-org
30  orgUrl: "https://org1.lightning.force.com",
31});
32dashboard.render();
33
34const visualization = new AnalyticsVisualization({
35  parentIdOrElement: "container2",
36  idOrApiName: "Viz2",
37  // Different org
38  orgUrl: "https://org2.lightning.force.com",
39});
40visualization.render();

The orgUrl is required when creating components in a multi org scenario, to ensure your component connects to the correct org.

Note

Adding Orgs Dynamically

You can add new orgs or retry failed orgs after initial SDK initialization using retryOrAddOrgs:

1import { retryOrAddOrgs } from "@salesforce/analytics-embedding-sdk";
2
3const newOrgs = [
4  {
5    // Lightning URL required
6    orgUrl: "https://org3.lightning.force.com",
7    authCredential: "https://org3-frontdoor.salesforce.com/...",
8  },
9  {
10    // Lightning URL required
11    orgUrl: "https://org4.lightning.force.com",
12    authCredential: "https://org4-frontdoor.salesforce.com/...",
13  },
14];
15const response = await retryOrAddOrgs(newOrgs);
16
17// Check if orgs were added successfully
18console.log(response.status);

The retryOrAddOrgs function returns the same BootstrapResponse format as initializeAnalyticsSdk.

Response

The initializeAnalyticsSdk function returns a BootstrapResponse object:

1const response = await initializeAnalyticsSdk(config);
2
3// Response structure:
4{
5    "message": "Sdk Initialize Complete",
6    "status": "Success",
7    "orgStates": {
8        "https://org1.lightning.force.com": {
9            "state": "INITIALIZATION_SUCCESS",
10            "reason": ""
11        },
12        "https://org2.lightning.force.com": {
13            "state": "INITIALIZATION_SUCCESS",
14            "reason": ""
15        }
16    }
17}
18
19// Check initialization status
20console.log(response.status);
21// Get detailed message
22console.log(response.message);
23
24// For multi-org scenarios, check individual org states:
25if (response.orgStates) {
26    response.orgStates.forEach((state, orgUrl) => {
27        console.log(`Org ${orgUrl}: ${state.state}`);
28    });
29}

Sample response:

1{
2  "message": "Sdk Initialize Complete",
3  "status": "Success",
4  "orgStates": {
5    "https://org1.lightning.force.com": {
6      "state": "INITIALIZATION_SUCCESS",
7      "reason": ""
8    },
9    "https://org2.lightning.force.com": {
10      "state": "INITIALIZATION_SUCCESS",
11      "reason": ""
12    }
13  }
14}

Status values:

Status.SUCCESS - All orgs initialized successfully
Status.PARTIAL_SUCCESS - Some orgs initialized successfully (multi-org only)
Status.FAILURE - Initialization failed

Logout

The SDK provides a logout function to log out from Salesforce orgs. The function returns a LogoutResponse with the same structure as BootstrapResponse.

1import { logout } from "@salesforce/analytics-embedding-sdk";
2
3// Logout from all orgs
4const response = await logout();
5
6// Logout from specific orgs
7const response = await logout([
8  "https://org1.lightning.force.com",
9  "https://org2.lightning.force.com",
10]);
11
12// 'Success', 'Partial Success', or 'Failure'
13console.log(response.status);
14// Detailed logout message
15console.log(response.message);

Sample response:

1{
2  "message": "Log out for all orgs complete",
3  "status": "Success",
4  "orgStates": {
5    "https://org1.lightning.force.com": {
6      "state": "LOGGED_OUT",
7      "reason": ""
8    },
9    "https://org2.lightning.force.com": {
10      "state": "LOGGED_OUT",
11      "reason": ""
12    }
13  }
14}

Need Help

Visit https://developer.salesforce.com/docs/analytics/sdk/guide/sdk-overview.html

Supported Desktop and Laptop Browsers

The SDK supports all browsers supported in Salesforce Lightning Experience.

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!