@salesforce/analytics-embedding-sdk
Advanced tools
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.
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.
npm install @salesforce/analytics-embedding-sdk --save
Note: The orgUrl parameter must be the Lightning URL (e.g., https://yourorg.lightning.force.com), not the my.salesforce.com domain URL.
import {AnalyticsDashboard, initializeAnalyticsSdk, type AnalyticsSdkConfig} from '@salesforce/analytics-embedding-sdk';
const config: AnalyticsSdkConfig = {
authCredential: "<%- auth-credential %>",
orgUrl: "<%- org_url %>" // Must be Lightning URL
};
await initializeAnalyticsSdk(config);
// parentIdOrElement is the target container (ID or element) and idOrApiName is the identifier or API name of the component to embed.
const dashboard: AnalyticsDashboard = new AnalyticsDashboard({parentIdOrElement: 'embed-here', idOrApiName: 'My_Sales_Dashboard'});
dashboard.render();
import {initializeAnalyticsSdk, AnalyticsDashboard} from '@salesforce/analytics-embedding-sdk';
const config = {
authCredential: "<%- auth-credential %>",
orgUrl: "<%- org_url %>" // Must be Lightning URL
};
await initializeAnalyticsSdk(config);
// parentIdOrElement is the target container (ID or element) and idOrApiName is the identifier or API name of the component to embed.
const dashboard = new AnalyticsDashboard({parentIdOrElement: 'embed-here', idOrApiName: 'My_Sales_Dashboard'});
dashboard.render();
<!DOCTYPE html>
<html>
<head>
<script type="module">
import {initializeAnalyticsSdk} from '@salesforce/analytics-embedding-sdk';
const config = {
authCredential: "<%- auth-credential %>",
orgUrl: "<%- org_url %>" // Must be Lightning URL
};
await initializeAnalyticsSdk({
authCredential: "<%- auth-credential %>",
orgUrl: "<%- org_url %>", // Must be Lightning URL
});
</script>
</head>
<body>
<analytics-dashboard id-or-api-name="My_Sales_Dashboard" height="500px">
</analytics-dashboard>
</body>
</html>
customViewId)You can pass an optional custom view ID so the embedded dashboard opens with the
same saved filter state (custom view) as in Tableau Next. This aligns with share
links that include a customViewId query parameter, and helps preserve dashboard
interactivity when embedding in other surfaces (for example Slack).
TypeScript / JavaScript — set customViewId on the dashboard props (or assign
dashboard.customViewId after construction):
const dashboard = new AnalyticsDashboard({
parentIdOrElement: 'embed-here',
idOrApiName: 'My_Sales_Dashboard',
customViewId: 'f5f0e1234aabcde67890'
});
await dashboard.render();
HTML — use the custom-view-id attribute on <analytics-dashboard>:
<analytics-dashboard
id-or-api-name="My_Sales_Dashboard"
custom-view-id="f5f0e1234aabcde67890"
height="500px"
></analytics-dashboard>
If your app parses a dashboard URL, read the customViewId query parameter and pass it
through as shown above.
Configure actions on the dashboard in Tableau Next using Salesforce Help: add actions to a dashboard.
Dashboard actions (buttons configured on the dashboard) are supported in third-party embedding. That includes actions such as Salesforce Flows, page navigation, and URL navigation, consistent with the embedded dashboard experience in Tableau Next.
The AnalyticsAgent component embeds your Analytics and Visualization agent powered by Agentforce. It helps users understand data through natural language insights, visualizations, and proactive alerts.
The agent supports two operating modes:
contextConfig to bind the agent to a specific dashboard, metric, or semantic model.contextConfig to automatically track all embedded AnalyticsDashboard and AnalyticsMetric components on the page.import {
AnalyticsAgent,
AgentContextType,
initializeAnalyticsSdk,
analyticsEventTarget,
EventName,
type AgentProps,
type AnalyticsSdkConfig
} from '@salesforce/analytics-embedding-sdk';
const config: AnalyticsSdkConfig = {
authCredential: '<%- auth-credential %>',
orgUrl: '<%- org_url %>' // Must be Lightning URL
};
await initializeAnalyticsSdk(config);
// Single-context mode: bind the agent to a specific dashboard
const agentProps: AgentProps = {
parentIdOrElement: 'agent-container',
idOrApiName: '<%- agent-id %>',
contextConfig: {
contextType: AgentContextType.DASHBOARD,
contextTypeIdOrApiName: 'My_Sales_Dashboard'
},
showHeader: true,
showHeaderActions: true,
agentName: 'Sales Insights',
welcomeText: 'Ask me anything about your sales data.'
};
const agent: AnalyticsAgent = new AnalyticsAgent(agentProps);
agent.render();
import {initializeAnalyticsSdk, AnalyticsAgent, AgentContextType} from '@salesforce/analytics-embedding-sdk';
const config = {
authCredential: '<%- auth-credential %>',
orgUrl: '<%- org_url %>' // Must be Lightning URL
};
await initializeAnalyticsSdk(config);
// Multi-component mode: omit contextConfig to track all embedded components automatically
const agent = new AnalyticsAgent({
parentIdOrElement: 'agent-container',
idOrApiName: '<%- agent-id %>',
showHeader: true,
showHeaderActions: true,
agentName: 'Sales Insights',
welcomeText: 'Ask me anything about your sales data.'
});
agent.render();
<!doctype html>
<html>
<head>
<script type="module">
import {initializeAnalyticsSdk} from '@salesforce/analytics-embedding-sdk';
await initializeAnalyticsSdk({
authCredential: '<%- auth-credential %>',
orgUrl: '<%- org_url %>' // Must be Lightning URL
});
</script>
</head>
<body>
<analytics-agent
id-or-api-name="<%- agent-id %>"
context-type="dashboard"
context-type-id-or-api-name="My_Sales_Dashboard"
show-header="true"
show-header-actions="true"
agent-name="Sales Insights"
welcome-text="Ask me anything about your sales data."
height="600px"
></analytics-agent>
</body>
</html>
The AgentContextType enum specifies the type of analytics asset to bind the agent to:
| Value | Description |
|---|---|
AgentContextType.DASHBOARD | Dashboard context |
AgentContextType.METRIC | Metric context |
AgentContextType.SDM | Semantic Model context |
Use the styleTokens property to theme the agent UI:
const agent = new AnalyticsAgent({
parentIdOrElement: 'agent-container',
idOrApiName: '<%- agent-id %>',
styleTokens: {
containerBackground: '#faf5ff',
headerBackground: '#ede9fe',
headerBlockTextColor: '#5b21b6',
messageBlockInboundBackgroundColor: '#ede9fe',
messageBlockOutboundBackgroundColor: '#7c3aed',
messageBlockOutboundTextColor: '#ffffff',
messageInputFooterSendButton: '#ec4899'
}
});
agent.render();
Call startNewAgentSession() to programmatically restart the conversation:
await agent.startNewAgentSession();
The SDK supports embedding components from multiple Salesforce orgs in a single application. Use orgConfigs instead of a single orgUrl and authCredential:
import {
initializeAnalyticsSdk,
AnalyticsDashboard,
AnalyticsVisualization,
AnalyticsAgent,
AgentContextType
} from '@salesforce/analytics-embedding-sdk';
// Initialize with multiple orgs
const initPayload = {
orgConfigs: [
{
orgUrl: 'https://org1.lightning.force.com', // Lightning URL required
authCredential: 'https://org1-frontdoor.salesforce.com/...'
},
{
orgUrl: 'https://org2.lightning.force.com', // Lightning URL required
authCredential: 'https://org2-frontdoor.salesforce.com/...'
}
]
};
const response = await initializeAnalyticsSdk(initPayload);
// Embed components from different orgs - always specify orgUrl
const dashboard = new AnalyticsDashboard({
parentIdOrElement: 'container1',
idOrApiName: 'Dashboard1',
orgUrl: 'https://org1.lightning.force.com' // Required for multi-org
});
dashboard.render();
const visualization = new AnalyticsVisualization({
parentIdOrElement: 'container2',
idOrApiName: 'Viz2',
orgUrl: 'https://org2.lightning.force.com' // Different org
});
visualization.render();
const agent = new AnalyticsAgent({
parentIdOrElement: 'container3',
idOrApiName: 'Agent1',
contextConfig: {
contextType: AgentContextType.DASHBOARD,
contextTypeIdOrApiName: 'Dashboard1'
},
orgUrl: 'https://org1.lightning.force.com' // Required for multi-org
});
agent.render();
Note:
orgUrl is required when creating components in a multi-org scenario, to ensure your component connects to the correct org.You can add new orgs or retry failed orgs after initial SDK initialization using retryOrAddOrgs:
import {retryOrAddOrgs} from '@salesforce/analytics-embedding-sdk';
const newOrgs = [
{
orgUrl: 'https://org3.lightning.force.com', // Lightning URL required
authCredential: 'https://org3-frontdoor.salesforce.com/...'
},
{
orgUrl: 'https://org4.lightning.force.com', // Lightning URL required
authCredential: 'https://org4-frontdoor.salesforce.com/...'
}
];
const response = await retryOrAddOrgs(newOrgs);
console.log(response.status); // Check if orgs were added successfully
The retryOrAddOrgs function returns the same BootstrapResponse format as initializeAnalyticsSdk.
The initializeAnalyticsSdk function returns a BootstrapResponse object:
const response = await initializeAnalyticsSdk(config);
// Response structure:
{
"message": "Sdk Initialize Complete",
"status": "Success",
"orgStates": {
"https://org1.lightning.force.com": {
"state": "INITIALIZATION_SUCCESS",
"reason": ""
},
"https://org2.lightning.force.com": {
"state": "INITIALIZATION_SUCCESS",
"reason": ""
}
}
}
console.log(response.status); // Check initialization status
console.log(response.message); // Get detailed message
// For multi-org scenarios, check individual org states:
if (response.orgStates) {
response.orgStates.forEach((state, orgUrl) => {
console.log(`Org ${orgUrl}: ${state.state}`);
});
}
Sample response:
{
"message": "Sdk Initialize Complete",
"status": "Success",
"orgStates": {
"https://org1.lightning.force.com": {
"state": "INITIALIZATION_SUCCESS",
"reason": ""
},
"https://org2.lightning.force.com": {
"state": "INITIALIZATION_SUCCESS",
"reason": ""
}
}
}
Status values:
Status.SUCCESS - All orgs initialized successfullyStatus.PARTIAL_SUCCESS - Some orgs initialized successfully (multi-org only)Status.FAILURE - Initialization failedFor a single org or multiple orgs, Salesforce may require an extra step before the session is valid—such as multi-factor authentication (MFA) or a forced password reset. In that case initializeAnalyticsSdk can return a non-success overall status while the affected org appears in response.orgStates with:
state: AUTH_REDIRECT (see OrgStates.AUTH_REDIRECT when importing the enum)redirectUrl: org-provided path (often relative)redirectOrigin: origin to combine with redirectUrlWhat to do
AUTH_REDIRECT, send the user to the challenge UI, typically by opening ${redirectOrigin}${redirectUrl} in a new window or tab (popups may be blocked; fall back to a full tab).retryOrAddOrgs for that org.Credentials when retrying
authCredential together with the same Lightning orgUrl.{ orgUrl, authCredential: orgUrl }, without generating a new frontdoor URL first. If that retry does not succeed, obtain a new frontdoor URL and retry with it.The retryOrAddOrgs response uses the same BootstrapResponse shape as initializeAnalyticsSdk, so you can inspect orgStates again for any remaining AUTH_REDIRECT or errors.
The SDK provides a logout function to log out from Salesforce orgs. The function returns a LogoutResponse with the same structure as BootstrapResponse.
import {logout} from '@salesforce/analytics-embedding-sdk';
// Logout from all orgs
const response = await logout();
// Logout from specific orgs
const response = await logout(['https://org1.lightning.force.com', 'https://org2.lightning.force.com']);
console.log(response.status); // 'Success', 'Partial Success', or 'Failure'
console.log(response.message); // Detailed logout message
Sample response:
{
"message": "Log out for all orgs complete",
"status": "Success",
"orgStates": {
"https://org1.lightning.force.com": {
"state": "LOGGED_OUT",
"reason": ""
},
"https://org2.lightning.force.com": {
"state": "LOGGED_OUT",
"reason": ""
}
}
}
The SDK supports all browsers supported in Salesforce Lightning Experience.
FAQs
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.
The npm package @salesforce/analytics-embedding-sdk receives a total of 37 weekly downloads. As such, @salesforce/analytics-embedding-sdk popularity was classified as not popular.
We found that @salesforce/analytics-embedding-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 28 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
GitHub account BufferZoneCorp published sleeper packages that later added credential theft, GitHub Actions tampering, fake go wrappers, and SSH persistence.
Research
/Security News
Socket found a malicious Intercom PHP package on Packagist using Composer plugin execution to steal credentials and spread across ecosystems.
Research
/Security News
Compromised intercom-client@7.0.4 npm package is tied to the ongoing Mini Shai-Hulud worm attack targeting developer and CI/CD secrets.