@salesforce/analytics-embedding-sdk

v1.0.0

Published

2 days ago

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.

Analytics Embedding SDK

Install

npm 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

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();

JavaScript

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();

HTML

<!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>

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:

import {initializeAnalyticsSdk, AnalyticsDashboard, AnalyticsVisualization} 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();

Note:

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

Adding Orgs Dynamically

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.

Response

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 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.

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": ""
		}
	}
}

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.