Build the Embedding Bridge Without a Salesforce Package

Embed an external web app in Salesforce and talk to the host without adding a @salesforce/* package to your app. An embedded app communicates with Salesforce over the sf-embedding protocol through a small piece of JavaScript called the bridge: it completes a one-time handshake, then exchanges JSON-RPC 2.0 messages with the host over a MessagePort. This guide shows how to build that bridge yourself, in plain JavaScript, and covers the message surface the deployed host implements today.

The sf-embedding protocol specification normatively defines the behavior described here. Where this guide and the specification disagree, the specification is authoritative.

Most apps use the Salesforce-provided guest SDK to talk to the host. Build the bridge yourself when you want full control over the protocol surface, want to avoid an added dependency, or want to integrate the protocol into an existing message layer. A hand-written, wire-level bridge is fully supported as long as it honors the message shapes described here.

• Your web app is hosted at an HTTPS URL that you control, on an origin that differs from your Salesforce org’s origin.
• A Salesforce host renders the lightning-ui-embedding component pointed at your app, and the org trusts your app’s origin for inline frames. See Get Started with UI Embedding.
• You’re comfortable working with window.postMessage, MessageChannel, and JSON-RPC 2.0 message shapes.

Communication happens in two phases.

1. Handshake (window.postMessage). The host loads your app in a cross-origin iframe and passes hostMetaData (which includes hostAppOrigin and instanceId) on the URL. Your app sends an sf-embedding/ready heartbeat, and the host replies by transferring a MessagePort.
2. Session (JSON-RPC 2.0 over the port). Every later message, whether a request, a response, or a notification, is standard JSON-RPC 2.0 framed over that port. MessageChannel delivers messages in order per port.

A JSON-RPC library isn’t required, but the JSON-RPC 2.0 message shape is required if you want to talk to the real Salesforce host. Keep two things separate.

• The message shape is the host’s contract. The deployed lightning-ui-embedding host emits and parses JSON-RPC 2.0 on the port. Requests are { jsonrpc: "2.0", id, method, params }, notifications drop the id, and responses carry the id plus a result or an error. The id is a monotonic, non-negative integer per side. A request can carry an optional _meta.traceId, which the host echoes on the reply. The host doesn’t understand anything else on the port. That’s a data format, not a dependency, so you can hand-build those objects, which is what the bridge in Step 2 does with no library.
• The handshake is not JSON-RPC. The heartbeat and bootstrap envelope are plain window.postMessage messages. JSON-RPC begins only after the MessagePort transfer.

The handshake is Salesforce-specific and security-critical, so follow it exactly. Read hostMetaData, send the heartbeat, and then wait for the MessagePort inside an sf-embedding.bootstrap envelope. Validate the envelope with five checks before you trust it.

Run the handshake once, as early as possible, such as a module-load side effect or a mount effect on your top-level layout, and reuse the single session promise everywhere. If you bootstrap lazily on first feature use, any screen that doesn’t touch the bridge on mount never handshakes. The failure is invisible because no error fires and the feature does nothing.

After the handshake, communication is plain JSON-RPC 2.0, so the bridge is small. It generates request IDs, correlates replies, dispatches inbound requests and notifications by method, and times out requests. Here’s the whole bridge, hand-written with no dependencies.

Right after the port is live, the host announces itself and you announce back. Then you subscribe to the host’s rendering state. Register your inbound handlers before you announce, so a fast host can’t get ahead of you.

• The host sends ui/notifications/host-initialized, the authoritative carrier of session identity (instanceId and hostInfo).
• You reply once with ui/notifications/embedding-initialized (your app’s name and version).
• You subscribe to ui/subscribe/ui-state to receive the host’s props and styles. The current snapshot arrives in the response, not as a separate notification.

If you send a request before the init lifecycle finishes, the host rejects it with NOT_INITIALIZED. Wait for ui/notifications/host-initialized, and then send your requests.

With the bridge in place, every protocol method is a request or a notification.

A few rules are worth internalizing.

• Every request gets a response. Notifications never reply. A request resolves with a result or rejects with an error. Only notifications are dropped silently, because they have no response path.
• One default timeout is enough. All shipping requests are quick, and the shipping host has no user-gated (indefinite) requests, so you don’t need to extend or disable the timeout for any method.
• Notifications are fire-and-forget. ui/notifications/resize is a size hint; the host applies its own layout policy and can honor, clamp, or ignore it. There’s no confirming response, so observe the outcome through window.innerWidth and window.innerHeight if you need to.
• Dirty-state rides on the event channel. There’s no dedicated method for it. Dispatch ui/events/dispatch with eventType: "trackdirtystate" and detail: { isDirty, instanceId, label }. Use the instanceId from the handshake. Omit it and the host drops the signal. The host re-emits trackdirtystate as a DOM event that a page author can bind to.

These are the messages a bridge uses over the port. None of them needs a Salesforce package, because you send and receive them all through the bridge. The handshake messages (the sf-embedding/ready heartbeat and the sf-embedding.bootstrap envelope) travel over window.postMessage, not the port. Every message in the table is JSON-RPC 2.0 over the port.

Every request gets a response. A failure comes back as a JSON-RPC error with a numeric code, an optional message, and optional data ({ retryable?, details? }). These are transport-level codes on the port, distinct from the component error codes reported on the sf-embedding.component.error DOM event. For those, see UI Embedding Error Codes.

METHOD_NOT_FOUND and INVALID_PARAMS are distinct. METHOD_NOT_FOUND means the host doesn’t know the method. INVALID_PARAMS means the method exists but your arguments are wrong. REQUEST_TIMEOUT is a client-side convention your bridge synthesizes, not a host error.

The bootstrap you hand-write is security-critical.

• Serve your app from a different origin than the host. The browser’s Same-Origin Policy isolates it. In local development, different ports count as different origins.
• Trust only hostAppOrigin. Verify event.origin === hostAppOrigin on the envelope, and send the heartbeat to that exact origin, never "*". Don’t maintain your own list of accepted host origins.
• Run all five envelope checks, and fail closed on a duplicate transfer. A second valid envelope means you shut the session down and never use the second port. The worst outcome is a denied session, never a hijacked one.
• Never let the port leak. Keep the MessagePort in local or module scope. Don’t put it on window, globalThis, or any shared registry.
• You handle your own authentication. The host gives you no credentials or data access, so authenticate to your own backend as usual.
• Sanitize error reports. Send only the method name, a category, and a path-only filename. Never send a message, a stack, or a reason.

Your app declares the single version it speaks in the heartbeat (protocolVersion: "1.0.0"). The host accepts it by transferring the port. To refuse the session, the host doesn’t transfer a port. Instead, it dispatches sf-embedding.component.error (code PROTOCOL_VERSION_MISMATCH) on its own element for the page to observe. The shipping host supports exactly 1.0.0. Pin to a version you’ve tested, and watch the protocol changelog.

• Get Started with UI Embedding
• Track Unsaved Changes in an Embedded App
• Resize an Embedded App to Fit Its Content
• UI Embedding Error Codes