Pulsar Platform - JS Bridge API
- Brad Sparks
- Kevin Jenkins
- Tyler Cupp (Unlicensed)
Getting Started with Pulsar as a Platform
Use Pulsar to seamlessly integrate your custom HTML/JavaScript application with your Salesforce data using the Pulsar JavaScript Bridge. This bridge provides a robust set of methods to communicate with the Pulsar JSAPI, enabling you to build customized, data-driven applications on the Pulsar platform.
Key Features
Easily access and manipulate Salesforce data within your web application.
Leverage the Pulsar JSAPI for advanced functionality.
Build a custom, interactive experience tailored to your needs.
Advanced or experienced users may wish to see some examples available on GitHub.
Retrieving the Pulsar JS Bridge
To integrate your application with Salesforce data on the Pulsar platform, you first need to retrieve the Pulsar JS Bridge. The bridge serves as the connection between your HTML/JavaScript application and the native Pulsar application, enabling seamless data access and interaction. This section will guide you through the necessary steps to obtain and initialize the Pulsar JS Bridge, ensuring your application is set up for smooth communication with Pulsar services.
Choosing the Right Method
There are two ways to retrieve the Pulsar JS Bridge, depending on your deployment environment:
Context | Description |
|---|---|
Native Context | Your document is loaded directly within the Pulsar platform (e.g., launched from an object detail page, home page tab, PSL, or a Lightning Bolt menu action). |
Embedded Context | Your document is loaded within Salesforce Field Service Lightning (SFS) via an embedded iframe. |
If your application needs to support both contexts, refer to the "Developing for Both" section below.
Native Context: Listening for the WebViewJavascriptBridgeReady Event
If your application is running inside the Pulsar native environment, you need to listen for the WebViewJavascriptBridgeReady event to retrieve the Pulsar JS Bridge.
IMPORTANT: Prior to Pulsar 12.0, you must call the init method on the bridge before you use it. The function you provide here will receive messages sent over the bridge. This is a great place to add some debug logging as you develop your application.
let pulsarJSBridge;
document.addEventListener('WebViewJavascriptBridgeReady', function(event) {
pulsarJSBridge = event.bridge;
// Check if running on Pulsar 12.0 or later, the version method was added
// with Pulsar 12.0 and will be undefined in earlier versions.
if (typeof pulsarJSBridge.version === 'undefined') {
pulsarJSBridge.init((message, responseCallback) => {
console.log('PulsarJSBridge received message: ', message);
});
}
// The bridge is now ready for use
console.log('Pulsar JS Bridge initialized:', pulsarJSBridge);
}, false);
Embedded Context: Copying from window.parent.pulsar
If your application runs inside Pulsar Field Service Lightning (i.e., an embedded iframe), the Pulsar JS Bridge is accessible via window.parent.pulsar.bridge. When we are in this context, it is also often useful to grab the pulsar object as well. This contains some additional methods to interact with the Pulsar FSL application.
There is no need to call the init method as this will have already been done by the Pulsar FSL application.
let pulsarJSBridge, pulsar;
if (window.parent.pulsar && window.parent.pulsar.bridge) {
pulsar = window.parent.pulsar;
pulsarJSBridge = window.parent.pulsar.bridge;
// there is no need to call init on this version of the bridge as it has already been initialized by Pulsar for SFS
} else {
console.warn('Something is wrong, unable to locate the Pulsar JS Bridge. Are you sure you are in an embedded state?')
}Developing for Both Contexts (Robust Method)
If your application needs to support both native and embedded contexts, use the following hybrid approach:
While this method is great for keeping your applications reusable, it is important to note that if you need to communicate with FSL you will need to obtain the pulsar object as well. This will require you to have branching logic in your own code which determines if you need to make use of that object.
// A bullet proof initialization method for obtaining the Pulsar Javascript Bridge.
async function initBridge() {
return new Promise((resolve, reject) => {
// First, check to see if we have a bridge present on our window. If so we can
// use it knowing that we are running in an embedded state.
if (window.parent.pulsar && window.parent.pulsar.bridge) {
this.bridge = window.parent.pulsar.bridge;
resolve(this.bridge);
} else {
// Otherwise, create a listener for the WebViewJavascriptBridgeReady event
let timeout;
const bridgeListener = (event) => {
this.bridge = event.bridge;
if (typeof this.bridge.version === 'undefined') {
this.bridge.init((message, responseCallback) => {
console.log('PulsarJSBridge received message:', message);
});
}
clearTimeout(timeout);
resolve(this.bridge);
};
// Add the listener
document.addEventListener('WebViewJavascriptBridgeReady', bridgeListener, { once: true });
// Allow a sensible amount of time for the bridge to be received, otherwise expect that we have
// an issue and reject, allowing the user to handle this case or simplely announce the error.
timeout = setTimeout(() => {
document.removeEventListener('WebViewJavascriptBridgeReady', bridgeListener);
reject(new Error('Failed to initialize Pulsar JS Bridge within 10 seconds'));
}, 10000);
}
});
}
// Example Usage
initBridge()
.then((bridge) => {
console.log('Pulsar JS Bridge initialized:', bridge);
// Begin using pulsarJSBridge
})
.catch((error) => {
console.error('Error initializing Pulsar JS Bridge:', error.message);
});Communicating with the Pulsar JSAPI
The primary way in which your custom application will interact with Pulsar is through the Pulsar JSAPI and the send method. Just about anything that can be done in the native Pulsar for Salesforce application can be done through a combination of the available methods in the Pulsar JSAPI, including reading, updating, and manipulating Salesforce data.
Pulsar JS Bridge Send Method
The send method enables your application to communicate with Pulsar by sending structured messages. Each message consists of an object with various required and optional properties which will be detailed below.
Example: JSAPI read Method
The following example demonstrates how to send a read request to retrieve Account records where the Name field is "Luminix". This will only return Accounts that have the exact name “Luminix” and not Accounts that have Name fields that contain “Luminix”.
// Sending a simple read request.
const request = {
type: 'read',
object: 'Account',
data: {
Name: 'Luminix'
}
};
pulsarJSBridge.send(request, function (responseData) {
console.log('Read response: ' + responseData);
});Modifying Data with the JSAPI
When modifying Salesforce data using create, update, or delete requests, ensure your data meets Salesforce field requirements:
✅ Required Fields: If a field is required in Salesforce, it must be included in your request.
✅ Data Types: Ensure field values match their expected data type (e.g., numbers, strings, booleans).
✅ Validation & Business Logic: Pulsar enforces Salesforce validation rules, triggers, and workflow logic just like the native interface.
Handling JSAPI Responses
The second argument to the send function is a callback that the native Pulsar platform will call when it resolves your request.
All responses will contain:
type (string) – A response type which corresponds to the request type. These are typically in the format <requestType>Response. For instance a read request will respond with readResponse.
Responses often include:
object(string) – The name of the Salesforce SObject (e.g. “Account, Contact that was included with the request.data(string or object or array) – The data returned from the request.
Successful Request Example
A successful create request for a Contact might return the following. The value in the data property is the Id of the created Contact.
{
"type" : "createResponse",
"object" : "Contact",
"data" : "X0123456789ID" // the Id of the created object
}Failed Request Example
A failed create request for a Contact might return the following. The value in the data property this time is the error message corresponding to the reason that this request failed.
{
"type" : "error",
"object" : "Contact,
"data" : "You must include a phone number for the Contact." // useful error string
}Bridge Methods
Beyond the send method, the Pulsar JS Bridge provides additional methods to interact with Pulsar in different ways. This section outlines these methods, their parameters, how they function, and when to use them.
init
The init() method initializes the Pulsar JavaScript Bridge. Although it is only required in versions prior to Pulsar 12.0, it remains a valuable entry point for setting up debugging, logging, or message monitoring in your application.
Example and Syntax
function debugMessageHandler(messageType, callback) {
console.log('Bridge message received: ', messageType);
}
bridge.init(messageHandler);Parameters
messageHandler(function, required) – A callback function that processes incoming bridge messages. It receives two arguments:
-messageType(string): The type of message received.
-callback(function): A user-defined handler to process the message payload or response.
send
The send(request, responseHandler) method is the primary way to interact with the Pulsar JSAPI. It allows your app to send structured requests and handle asynchronous responses from the bridge.
Every request must include a type field, which identifies the specific JSAPI method being invoked and an object field which can be an empty object {} for some requests. Depending on the method, additional properties such as object or args may also be required.
Example and Syntax
const request = {
'type': 'read',
'object': 'Contact',
'data': { 'Id': 'X1234567890' }
};
bridge.send(request, function(response) {
if (response.type === 'readResponse') {
doSomething(response.data);
} else if (response.type === 'error') {
console.error('There was an error reading the Contact.');
}
});Parameters
request(required, object) – an object that has at least the following properties:
Request Object Properties:type(required, string) – specifies the JSAPI method to invoke (e.g.'create','read','syncdata').data(required, object) – used to pass information to the JSAPI method. For methods that do not require any information, pass an empty object{}.object(optional, string) – Represents the Salesforce object type the operation is acting on (e.g.'Account','Contact').args(optional, object) – Sometimes used to provide context or information about how the JSAPI method should act on the data.
responseHandler(required, function) – A callback that handles the asynchronous response from the JSAPI call. It typically receives a response object with atypeanddata.
Each JSAPI method has its own expectations for which fields (besides type and data) are required or used.
Best Practices
Always verify which fields are required for the JSAPI method you're calling.
Include robust error handling in the
responseHandlerfor resilience.Structure your
datapayloads to match the expected shape (e.g., field names must match Salesforce API names).
registerHandler / deregisterHandler
The registerHandler(handlerName, handlerFunction) and deregisterHandler(handlerName) methods allow your app to listen for asynchronous events emitted by Pulsar, often outside the direct response lifecycle of a request. These handlers are commonly used to monitor system-level activities like sync progress, layout changes, or custom authentication flows.
When to Use
Use registerHandler(handlerName, handlerFunction) to listen for specific events. For example, you might:
Show a loading indicator when a sync starts (
syncDataStarted)Update a progress bar (
syncDataUpdate)Perform cleanup tasks when sync completes (
syncDataFinished)
To stop listening for an event, call deregisterHandler(handlerName).
registerHandler Parameters
handlerName(required, string) – A name corresponding to one of the special Pulsar events:'dispatchToHomeApp','invalidateLayout','syncDataStarted','syncDataUpdate','syncDataCoreFinished','syncDataFinished','custom_oauth'.handlerFunction(required, function) – a callback that will possibly receive an object as an argument with results from the event.
deregisterHandler Parameters
handlerName(required, string) – A name corresponding to one of the special Pulsar events:'dispatchToHomeApp','invalidateLayout','syncDataStarted','syncDataUpdate','syncDataCoreFinished','syncDataFinished','custom_oauth'.
Example Syntax
// Register an event handler
bridge.registerHandler('syncDataFinished', function(dataObj) {
console.log('Sync has finished!');
// Deregister the event handler
bridge.deregisterHandler('syncDataFinished');
});
When working in an Embedded Context use the registerHandler and deregisterHandler methods very carefully. Because you are using the exact same PulsarJSBridge as the parent document, calling deregisterHandler will remove all registered handlers from the parent document as well. Bridges provided through the Native Context are stamped with different identifiers that allow Pulsar to avoid this conflict.
When working in an Embedded Context do NOT register for any of the syncData methods - e.g. syncDataUpdate or syncDataFinished. Instead, you can make use of special methods attached to the pulsar object obtained when you acquired the bridge. addSyncDataUpdateHandler and addSyncFinishedHandler and their corresponding removeSyncDataUpdateHandler and removeSyncFinishedHandler.
Special Events You Can Register For
Event Name | Description |
|---|---|
| Emitted when Pulsar wants to send a message to a custom home screen (e.g., Pulsar for SFS). |
| Triggered when Salesforce layout metadata changes. Use this to re-fetch layout/schema info and re-render affected components. |
| Fired when a data sync begins. Useful for showing loading indicators. |
| Emitted periodically during sync. Contains fields like |
| Triggered when the core data portion of the sync completes, though additional content (e.g., documents, images) may still be syncing. |
| Indicates the full sync process has completed (including documents and metadata). |
| Pulsar 12.0+ only. Emitted after a custom OAuth 2.0 authentication flow completes and the |
getDocumentPath
This method is used to generate a path to a given document node in your custom app. It takes a document node as an argument and will walk the DOM and build a string that can be used by native Pulsar when generating PDFs. This was designed specifically for this function and was meant to help construct arguments for PDF generation, namely providing the header, body and footer nodes.
version
Starting with Pulsar 12.0.0, we have included a version stamp for the Pulsar JS Bridge. This is purely informational but can be used to ensure backward compatibility.