Getting Started

The following examples are also available on GitHub.

Integrating your HTML/Javascript solution with your Salesforce data stored in Pulsar is easy with the Pulsar JS Bridge. The Pulsar JS Bridge has methods to communicate with the Pulsar JSAPI with which you can build a powerful customized application on the Pulsar platform. In order to use the Pulsar JS Bridge, you’ll need to know how to retrieve it.

Retrieving the Pulsar JS Bridge

There are two ways to retrieve the bridge and you should choose the one that fits you context.

1. Native Context: Listening for the WebViewJavascriptBridgeReady Document event. Native context implies a document loaded through native Pulsar interactions. This includes: launching from an object detail page, a home page tab, a home page replacement app, launching from the content library, loaded from PSL or a Lightning Bolt Menu action.
   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; // the presence of pulsarJSBridge.version implies that we are running Pulsar 12.0 if (typeof pulsarJSBridge.version === 'undefined') { pulsarJSBridge.init( function(message, responseCallback) { // Add a log for every message that is sent to the Pulsar JS Bridge console.log('PulsarJSBridge received message: ', message); } ); } // you can now make use of pulsarJSBridge! // Read on to learn how to send and receive messages as well as best practices for setting up the bridge. }, false);

    

2. Embedded Context: Copying it from window.parent.pulsar. Embedded context implies a document loaded through the Pulsar Field Service Lightning 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?') }

Sending Messages and Data

The primary way in which your custom application will interact with Pulsar is through the Pulsar JSAPI and the send method.

Pulsar responds to messages consisting of an object with two to four members ('type', 'object', 'data', and 'field'). Pulsar does not send adhoc messages to the document, but if you want your app to respond to them anyway, use the callback function argument to “bridge.init".

For requests that modify data, always remember to adhere to requirements- if a field is required on salesforce, It will be required to save the object here. The bridge serializes to JSON, so also be sure the field values are the correct "types". Pulsar should handle the rest, but also keep in mind that Pulsar handles each type of request in the same manner as it would from the native Pulsar interface- any PulsarSetting (and SFDC if online) trigger logic and custom validation rules should apply in most case.

Receiving Responses

Successful Requests

Failed Requests

Best Practices

Creating a Custom Bridge Wrapper

We highly recommend that you develop your own wrapper class or object around the Pulsar JS Bridge.

Advanced Topics

Bridge Methods

init

The init(messageHandler) method is required to be called prior to making use of the Pulsar JS Bridge. It requires a single argument which is a function that takes two arguments – a string that defines the message type and the user defined callback function that will handle the message response. This handler is typically used for debugging purposes and is a great place to add conditional logging to track what messages are being sent to the bridge from your application.

send

The send(request, responseHandler) method is how requests are sent to the Pulsar JSAPI. Request objects must have a type property and can optionally also include object, data and/or field. type specifies the target JSAPI method. object, data, field are all utilized by the JSAPI methods to perform the requested action. Each JSAPI method has different requirements of these fields. object typically refers to the Salesforce object type on which the JSAPI will be operating on. data can be almost anything, but frequently is used to specify field : data value pairs for CRUD interactions. field is infrequently used, but often references a specific field on the object.

registerHandler / deregisterHandler

The registerHandler(handler) and deregisterHandler(handler are used to listen for special messages sent from Pulsar (often not in direct response to a request). The most common example of this is getting information related to sync activity. You application could register for syncDataStarted and syncDataFinished to give some indication to the user that a sync is in progress.

Here is a list of events that you can register to listen for and a general description for each.

1. ‘dispatchToHomeApp’ – issued by Pulsar to communicate with the home page replacement app. When Pulsar for SFS is enabled, this sends messages intended for use by Pulsar for SFS.

2. 'invalidateLayout’ – issued by Pulsar when we have received an update to the Salesforce objects layout information. An application may need to re-read layout or schema information in this case in order to re-render a layout properly.

3. ‘syncDataStarted’ – issued by Pulsar to indicate that a data sync has started.

4. ‘syncDataUpdate’ – issued by Pulsar to inform an update about the status of a sync. Information in this message will include a percentage complete.

5. ‘syncDataCoreFinished’ – issued by Pulsar when the data part of a sync has completed. Indicating that documents or images may still need to be sync’d.

6. ‘syncDataFinished’ – issued by Pulsar to indicate that the sync is completed.

7. ‘custom_oauth’ – issued by Pulsar when an external or internal custom OAuth 2.0 flow has completed and the pulsar custom_oauth callback deep link is used. (this is a Pulsar 12.0.0 feature)

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.